GetResponse Product Variants API

openapi: 3.0.0
info:
  title: GetResponse APIv3 Product Variants
  version: 3.2026-07-28T07:58:55+00:00
  description: The Product Variants operations of the GetResponse APIv3, split by tag from the provider-published
    OpenAPI at https://apireference.getresponse.com/open-api.json
  contact:
    name: API Support - DevZone
    url: https://app.getresponse.com/feedback.html?devzone=yes
    email: getresponse-devzone@cs.getresponse.com
servers:
- url: https://api.getresponse.com/v3
  description: GetResponse
- url: https://api3.getresponse360.com/v3
  description: GetResponse MAX US
- url: https://api3.getresponse360.pl/v3
  description: GetResponse MAX PL
tags:
- name: Product Variants
  description: Product Variants API documentation
paths:
  /shops/{shopId}/products/{productId}/variants:
    get:
      tags:
      - Product Variants
      summary: Get a list of product variants
      description: '

        Sending a **GET** request to this URL returns a collection of product variant resources that belong
        to the given shop and product.


        You can narrow down the list of resources by passing proper query parameters (the list of which
        you can find below in the request params section). You can basically search by:

        * name

        * sku

        * description


        The `description` fields can be a pattern and we''ll try to match this phrase.


        '
      operationId: getProductVariantList
      parameters:
      - name: query[name]
        in: query
        description: Search variant by name
        required: false
        schema:
          type: string
      - name: query[sku]
        in: query
        description: Search variant by SKU
        required: false
        schema:
          type: string
      - name: query[description]
        in: query
        description: Search variant by description
        required: false
        schema:
          type: string
      - name: query[externalId]
        in: query
        description: Search variant by external ID
        required: false
        schema:
          type: string
      - name: query[createdAt][from]
        in: query
        description: Show variants starting from this date
        required: false
        schema:
          type: string
          format: date-time
      - name: query[createdAt][to]
        in: query
        description: Show variants starting to this date
        required: false
        schema:
          type: string
          format: date-time
      - name: sort[createdOn]
        in: query
        description: Sort by date
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          $ref: '#/components/responses/ProductVariantList'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 404
                    code: 1013
                    codeDescription: The requested resource was not found
                    message: Resource not found
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1013
                    context:
                      contactId: pVyRW
                    uuid: 87b90a96-5ee5-4ca4-8180-ac00adcf62c7
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context
                      section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method
                      details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota
                      window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
    parameters:
    - $ref: '#/components/parameters/shopId'
    - $ref: '#/components/parameters/productId'
    post:
      tags:
      - Product Variants
      summary: Create product variant
      description: '

        Sending a **POST** request to this URL will create a new product variant resource.


        In order to create a new product variant, you need to send a product variant resource in the body
        of the request (remember that you need to serialize the body into a JSON string)


        There is no need to create every element (like: image, meta field, tax) one by one by their own
        endpoints. All these elements can be created during this method.


        '
      operationId: createProductVariant
      requestBody:
        $ref: '#/components/requestBodies/NewProductVariant'
      responses:
        '201':
          $ref: '#/components/responses/ProductVariantDetails'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 404
                    code: 1013
                    codeDescription: The requested resource was not found
                    message: Resource not found
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1013
                    context:
                      contactId: pVyRW
                    uuid: 87b90a96-5ee5-4ca4-8180-ac00adcf62c7
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context
                      section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method
                      details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota
                      window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
  /shops/{shopId}/products/{productId}/variants/{variantId}:
    get:
      tags:
      - Product Variants
      summary: Get a single product variant by ID
      description: '

        This method returns product variant according to the given `variantId` in the context of a given
        `shopId` and `productId`


        '
      operationId: getProductVariantById
      parameters:
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          $ref: '#/components/responses/ProductVariantDetails'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 404
                    code: 1013
                    codeDescription: The requested resource was not found
                    message: Resource not found
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1013
                    context:
                      contactId: pVyRW
                    uuid: 87b90a96-5ee5-4ca4-8180-ac00adcf62c7
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context
                      section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method
                      details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota
                      window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
    parameters:
    - $ref: '#/components/parameters/shopId'
    - $ref: '#/components/parameters/productId'
    - $ref: '#/components/parameters/variantId'
    post:
      tags:
      - Product Variants
      summary: Update product variant
      description: "\nUpdate properties of a product variant. You should send only those fields that need\
        \ to be changed. The remaining properties will stay the same. However, when updating metafields,\
        \ images, and taxes, you need to send entire collections. Individual fields can't be updated.\
        \ If you want to update particular metafields or tax resources, you can do so using their particular\
        \ endpoints, i.e:\n\n * taxes - `POST /v3/shops/{shopId}/taxes/{taxId}`\n * metaFields - `POST\
        \ /v3/shops/{shopId}/meta-fields/{metaFieldId}`\n\n"
      operationId: updateProductVariant
      requestBody:
        $ref: '#/components/requestBodies/UpdateProductVariant'
      responses:
        '200':
          $ref: '#/components/responses/ProductVariantDetails'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 404
                    code: 1013
                    codeDescription: The requested resource was not found
                    message: Resource not found
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1013
                    context:
                      contactId: pVyRW
                    uuid: 87b90a96-5ee5-4ca4-8180-ac00adcf62c7
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context
                      section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method
                      details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota
                      window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
    delete:
      tags:
      - Product Variants
      summary: Delete product variant
      description: ''
      operationId: deleteProductVariant
      responses:
        '204':
          description: Delete product variant
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 404
                    code: 1013
                    codeDescription: The requested resource was not found
                    message: Resource not found
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1013
                    context:
                      contactId: pVyRW
                    uuid: 87b90a96-5ee5-4ca4-8180-ac00adcf62c7
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context
                      section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method
                      details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota
                      window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
components:
  headers:
    CurrentPage:
      description: The current page number
      schema:
        type: integer
        format: int32
    RateLimitLimit:
      description: The total number of requests available per time frame
      schema:
        type: integer
        format: int32
    RateLimitRemaining:
      description: The number of requests left in the current time frame
      schema:
        type: integer
        format: int32
    RateLimitReset:
      description: Seconds left in the current time frame, e.g. "432 seconds"
      schema:
        type: string
    TotalCount:
      description: The total number of resources found for the specified conditions
      schema:
        type: integer
        format: int32
    TotalPages:
      description: The total number of pages
      schema:
        type: integer
        format: int32
  parameters:
    Fields:
      name: fields
      in: query
      description: List of fields that should be returned. Id is always returned. Fields should be separated
        by comma
      required: false
      schema:
        type: string
    Page:
      name: page
      in: query
      description: Page number
      required: false
      schema:
        type: integer
        format: int32
        default: 1
        minimum: 1
    PerPage:
      name: perPage
      in: query
      description: Requested number of results per page
      required: false
      schema:
        type: integer
        format: int32
        default: 100
        maximum: 1000
        minimum: 1
    productId:
      name: productId
      in: path
      description: The product ID
      required: true
      schema:
        type: string
      example: 9I
    shopId:
      name: shopId
      in: path
      description: The shop ID
      required: true
      schema:
        type: string
      example: pf3
    variantId:
      name: variantId
      in: path
      description: The variant ID
      required: true
      schema:
        type: string
      example: VTB
  requestBodies:
    NewProductVariant:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewProductVariant'
    UpdateProductVariant:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateProductVariant'
  responses:
    ProductVariantDetails:
      description: The product variant details
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProductVariant'
    ProductVariantList:
      description: The list of product variants
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        CurrentPage:
          $ref: '#/components/headers/CurrentPage'
        TotalPages:
          $ref: '#/components/headers/TotalPages'
        TotalCount:
          $ref: '#/components/headers/TotalCount'
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ProductVariant'
  schemas:
    BaseMetaField:
      properties:
        href:
          description: Direct hyperlink to a resource
          type: string
          format: uri
          readOnly: true
          example: https://api.getresponse.com/v3/shops/pf3/meta-fields/NoF
        metaFieldId:
          description: The meta field ID
          type: string
          readOnly: true
          example: NoF
        name:
          description: The meta field name
          type: string
          maxLength: 63
          minLength: 3
          example: Shoe size
        value:
          description: The meta field value
          type: string
          maxLength: 65000
          minLength: 0
          example: '11'
        valueType:
          description: The value type enumerable
          type: string
          enum:
          - string
          - integer
          example: integer
        description:
          description: The meta field description
          type: string
          maxLength: 255
          minLength: 0
          example: Description of this meta field
      type: object
    BaseProductVariant:
      properties:
        variantId:
          description: The product ID
          type: string
          readOnly: true
          example: VTB
        href:
          description: Direct hyperlink to a resource
          type: string
          format: uri
          readOnly: true
          example: https://api.getresponse.com/v3/shops/pf3/products/9I/variants/VTB
        name:
          description: The product name
          type: string
          maxLength: 255
          minLength: 1
          example: Red Monster Cap
        url:
          description: The external URL to the product variant
          type: string
          format: uri
          maxLength: 2048
          example: https://somedomain.com/products-variants/986
        sku:
          description: The stock-keeping unit of a variant. Must be unique within the product
          type: string
          maxLength: 255
          minLength: 2
          example: SKU-1254-56-457-5689
        price:
          description: The price
          type: number
          format: double
          example: 20
        priceTax:
          description: The price including tax
          type: number
          format: double
          example: 27.5
        previousPrice:
          description: The price before the change
          type: number
          format: double
          example: 25
          nullable: true
        previousPriceTax:
          description: The price before the change including tax
          type: number
          format: double
          example: 33.6
          nullable: true
        quantity:
          description: The quantity of variant items
          type: integer
          format: int64
          default: 1
        position:
          description: The position of a variant
          type: integer
          format: int64
          example: 1
        barcode:
          description: The barcode of a variant
          type: string
          maxLength: 255
          minLength: 2
          example: '12455687'
        externalId:
          description: The external ID is the identifying string or number of the variant given by another
            software
          type: string
          maxLength: 255
          example: ext1456
        description:
          description: The description of a variant
          type: string
          maxLength: 1000
          minLength: 2
          example: Red Cap with GetResponse Monster print
        images:
          type: array
          items:
            $ref: '#/components/schemas/NewProductVariantImage'
        metaFields:
          type: array
          items:
            $ref: '#/components/schemas/NewMetaField'
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/NewTax'
      type: object
    BaseTax:
      properties:
        taxId:
          description: The tax ID
          type: string
          readOnly: true
          example: Sk
        href:
          description: Direct hyperlink to a resource
          type: string
          format: uri
          readOnly: true
          example: https://api.getresponse.com/v3/shops/pf3/taxes/Sk
        name:
          description: The tax name
          type: string
          maxLength: 255
          minLength: 2
          example: VAT
        rate:
          description: The rate value
          type: number
          format: double
          maximum: 99.9
          minimum: 0
          example: 23
      type: object
    CreateAndUpdate:
      properties:
        createdOn:
          description: The creation date
          type: string
          format: date-time
          readOnly: true
        updatedOn:
          description: The date of the last update
          type: string
          format: date-time
          readOnly: true
      type: object
    ErrorResponse:
      required:
      - httpStatus
      - code
      - codeDescription
      - message
      - moreInfo
      - context
      - uuid
      properties:
        httpStatus:
          description: HTTP response code
          type: integer
          format: int32
        code:
          description: API error code
          type: integer
          format: int32
        codeDescription:
          description: API error code description
          type: string
        message:
          description: Error message
          type: string
        moreInfo:
          description: URL to error description in the API Docs
          type: string
        context:
          type: object
        uuid:
          description: UUID of the error response
          type: string
      type: object
    NewMetaField:
      required:
      - name
      - value
      - valueType
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseMetaField'
    NewProductVariant:
      required:
      - name
      - price
      - priceTax
      - sku
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseProductVariant'
    NewProductVariantImage:
      required:
      - src
      - position
      properties:
        imageId:
          description: The image ID
          type: string
          readOnly: true
          example: hY
        href:
          description: Direct hyperlink to a resource
          type: string
          format: uri
          readOnly: true
          example: https://api.getresponse.com/v3/shops/pf3/images/hY
        src:
          description: The source URL of an image
          type: string
          format: uri
          example: http://somedomain.com/images/src/img58db7ec64bab9.png
        position:
          description: The position of an image
          type: integer
          format: int32
          example: '1'
      type: object
    NewTax:
      required:
      - na

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/getresponse/refs/heads/main/openapi/getresponse-product-variants-openapi.yml