Beeketing Product API

openapi: 3.2.0
info:
  title: ShopBase Internal Product API
  termsOfService: http://swagger.io/terms/
  version: 1.0.0
  contact:
    url: /
    email: support@shopbase.com
  license:
    name: ShopBase Dev 1.0
    url: https://www.shopbase.net
  x-logo:
    url: https://admin-cdn.shopbase.com/img/Compact.ac400184.svg
  description: The Product resource lets you update and create products in a merchant's store. You can use product variants with the Product resource to create or update different versions of the same product. You can also add or update product images. </br></br>You can add products to collections with the CustomCollection resource and the SmartCollection resource
servers:
- url: https://shop-name.onshopbase.com
tags:
- description: The Product resource lets you update and create products in a merchant's store. You can use product variants with the Product resource to create or update different versions of the same product. You can also add or update product images. </br></br>You can add products to collections with the CustomCollection resource and the SmartCollection resource
  name: Product
paths:
  /admin/products.json:
    get:
      summary: Retrieves a list of products.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsSwaggerResponse'
      parameters:
      - name: ids
        description: Return only certain products, specified by a comma-separated list of product IDs.
        in: query
        required: false
        schema:
          type: string
      - name: limit
        description: 'Return up to this many results per page. (default: 50, maximum: 250).'
        in: query
        required: false
        schema:
          type: integer
      - name: since_id
        description: Restrict results to after the specified ID.
        in: query
        required: false
        schema:
          type: integer
      - name: title
        description: Filter results by product title.
        in: query
        required: false
        schema:
          type: string
      - name: vendor
        description: Filter results by vendor.
        in: query
        required: false
        schema:
          type: string
      - name: handle
        description: Filter results by handle.
        in: query
        required: false
        schema:
          type: string
      - name: product_type
        description: Filter results by product type.
        in: query
        required: false
        schema:
          type: string
      - name: collection_id
        description: Filter results by product collection ID.
        in: query
        required: false
        schema:
          type: integer
      - name: created_at_min
        description: 'Show products created after date. (format: 2014-04-25T16:15:47-04:00)'
        in: query
        required: false
        schema:
          type: string
      - name: created_at_max
        description: 'Show products created before date. (format: 2014-04-25T16:15:47-04:00)'
        in: query
        required: false
        schema:
          type: string
      - name: updated_at_min
        description: 'Show products last updated after date. (format: 2014-04-25T16:15:47-04:00)'
        in: query
        required: false
        schema:
          type: string
      - name: updated_at_max
        description: 'Show products last updated before date. (format: 2014-04-25T16:15:47-04:00)'
        in: query
        required: false
        schema:
          type: string
      - name: published_at_min
        description: 'Show products published after date. (format: 2014-04-25T16:15:47-04:00)'
        in: query
        required: false
        schema:
          type: string
      - name: published_at_max
        description: 'Show products published before date. (format: 2014-04-25T16:15:47-04:00)'
        in: query
        required: false
        schema:
          type: string
      - name: published_status
        description: 'Return products by their published status. (default: any), published: Show only published products. unpublished: Show only unpublished products. any: Show all products.'
        in: query
        required: false
        schema:
          type: string
      - name: fields
        description: Show only certain fields, specified by a comma-separated list of field names.
        in: query
        required: false
        schema:
          type: string
      - name: presentment_currencies
        description: Return presentment prices in only certain currencies, specified by a comma-separated list of ISO 4217 currency codes.
        in: query
        required: false
        schema:
          type: string
      - name: sort_field
        description: Sort result-set in ascending or descending order by that field.
        in: query
        required: false
        schema:
          type: string
      - name: sort_mode
        description: 'Ascending or descending order. (default: asc)'
        in: query
        required: false
        schema:
          type: string
      tags:
      - Product
      operationId: get-all-products
      security:
      - APP_ACCESS_TOKEN:
        - read_products
    delete:
      summary: Delete multi product.
      description: Delete multi product along with all its variants and images by ids
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDeleteMultiSwaggerResponse'
      parameters:
      - name: ids
        description: Product id
        in: path
        required: true
        schema:
          type: integer
      tags:
      - Product
      operationId: delete-multi-products
      security:
      - APP_ACCESS_TOKEN:
        - write_products
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductDeleteMultiSwaggerRequest'
              description: Product delete multi struct
        description: Product delete multi struct
        required: true
    post:
      summary: Create a new product.
      description: Create a new product.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSwaggerResponse'
      tags:
      - Product
      operationId: create-a-product
      security:
      - APP_ACCESS_TOKEN:
        - write_products
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductSwaggerRequest'
              description: Product request
        description: Product request
        required: true
    patch:
      summary: Patch multiple product.
      description: Patch multi product by options
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchProductResponseSwagger'
      tags:
      - Product
      operationId: patch-multiple-product
      security:
      - APP_ACCESS_TOKEN:
        - write_products
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductPatchRequest'
              description: Patch request
        description: Patch request
        required: true
  /admin/products/collections.json:
    get:
      summary: Retrieves a list of products of a collection.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsByCollectionSwaggerResponse'
      tags:
      - Product
      operationId: get-products-by-collection-id
      security:
      - APP_ACCESS_TOKEN:
        - read_products
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.ProductRequest'
              description: Product request
        description: Product request
  /admin/products/count.json:
    get:
      summary: Retrieves a count of products.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountResponse'
      parameters:
      - name: vendor
        description: Filter results by product vendor.
        in: query
        required: false
        schema:
          type: string
      - name: product_type
        description: Filter results by product type.
        in: query
        required: false
        schema:
          type: string
      - name: collection_id
        description: Filter results by collection ID.
        in: query
        required: false
        schema:
          type: integer
      - name: created_at_min
        description: 'Show products created after date. (format: 2014-04-25T16:15:47-04:00)'
        in: query
        required: false
        schema:
          type: string
      - name: created_at_max
        description: 'Show products created before date. (format: 2014-04-25T16:15:47-04:00)'
        in: query
        required: false
        schema:
          type: string
      - name: updated_at_min
        description: 'Show products last updated after date. (format: 2014-04-25T16:15:47-04:00)'
        in: query
        required: false
        schema:
          type: string
      - name: updated_at_max
        description: 'Show products last updated before date. (format: 2014-04-25T16:15:47-04:00)'
        in: query
        required: false
        schema:
          type: string
      - name: published_at_min
        description: 'Show products published after date. (format: 2014-04-25T16:15:47-04:00)'
        in: query
        required: false
        schema:
          type: string
      - name: published_at_max
        description: 'Show products published before date. (format: 2014-04-25T16:15:47-04:00)'
        in: query
        required: false
        schema:
          type: string
      - name: published_status
        description: Return products by their published status
        in: query
        required: false
        schema:
          type: string
      tags:
      - Product
      operationId: get-count-of-all-products
      security:
      - APP_ACCESS_TOKEN:
        - read_products
  /admin/products/tags.json:
    get:
      summary: Get tags from products
      description: Get tags from products
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponseProductTagsDto'
      parameters:
      - name: limit
        description: returns the number of tags want to display.
        in: query
        required: false
        schema:
          type: integer
      tags:
      - Product
      operationId: get-all-tag-of-product-in-shop
      security:
      - APP_ACCESS_TOKEN:
        - read_products
  /admin/products/types.json:
    get:
      summary: Get all types from all products
      description: Get all types from all products
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductGetTypesSwaggerResponse'
      parameters:
      - name: limit
        description: returns the up to this many results
        in: query
        required: false
        schema:
          type: integer
      tags:
      - Product
      operationId: get-all-types-of-products-in-shop
      security:
      - APP_ACCESS_TOKEN:
        - read_products
  /admin/products/vendors.json:
    get:
      summary: Get all vendors from all products
      description: Get all vendors from all products
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductGetVendorsSwaggerResponse'
      parameters:
      - name: limit
        description: returns the up to this many results
        in: query
        required: false
        schema:
          type: integer
      tags:
      - Product
      operationId: get-all-vendors-of-products-in-shop
      security:
      - APP_ACCESS_TOKEN:
        - read_products
  /admin/products/{product_id:(?:\\d+)}.json:
    get:
      summary: Retrieves a single product.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponseProductDto'
      parameters:
      - name: product_id
        description: Product ID.
        in: path
        required: true
        schema:
          type: integer
      - name: fields
        description: A comma-separated list of fields to include in the response.
        in: query
        required: false
        schema:
          type: string
      tags:
      - Product
      operationId: get-detail-of-a-product
      security:
      - APP_ACCESS_TOKEN:
        - read_products
  /admin/products/{product_id:[0-9]+}/remove_mapping.json:
    delete:
      summary: Remove mapping of single product from a fulfillment service.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductRemoveMappingResponse'
      parameters:
      - name: app_code
        description: 'App code, eg: alidropcon, phub...'
        in: query
        required: true
        schema:
          type: string
      tags:
      - Product
      operationId: remove-product-mapping-with-fulfillment-services
      security:
      - APP_ACCESS_TOKEN:
        - write_products
  /admin/products/{product_id:[0-9]+}/reorder-options.json:
    put:
      summary: Reorder product variants
      description: Reorder product variants.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSwaggerResponse'
      tags:
      - Product
      operationId: reorder-variant-of-product
      security:
      - APP_ACCESS_TOKEN:
        - write_products
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductReorderRequest'
              description: Product struct
        description: Product struct
        required: true
  /admin/products/{product_id}.json:
    delete:
      summary: Deletes a product.
      description: Delete a product along with all its variants and images
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwaggerDeleteResponse'
      parameters:
      - name: product_id
        description: Product ID
        in: path
        required: true
        schema:
          type: integer
      tags:
      - Product
      operationId: delete-a-product
      security:
      - APP_ACCESS_TOKEN:
        - write_products
    put:
      summary: Updates a product.
      description: Updates a product and its variants and images.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSwaggerResponse'
      parameters:
      - name: product_id
        description: Product ID
        in: path
        required: true
        schema:
          type: integer
      tags:
      - Product
      operationId: update-a-product
      security:
      - APP_ACCESS_TOKEN:
        - write_products
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductUpdateRequestSwagger'
              description: Product update request struct
        description: Product update request struct
        required: true
  /admin/products/{product_id}/variants/duplicate.json:
    post:
      summary: Duplicate product variants
      description: Duplicate product variants
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductVariantDuplicateResponseSwagger'
      tags:
      - Product
      operationId: duplicate--variants-of-a-product
      security:
      - APP_ACCESS_TOKEN:
        - write_products
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductVariantDuplicateRequest'
              description: Product variant duplicate request
        description: Product variant duplicate request
        required: true
components:
  schemas:
    APIResponseProductDto:
      properties:
        product:
          $ref: '#/components/schemas/ProductDto'
      type: object
    dto.Condition:
      properties:
        relation:
          type: string
          description: Condition relation
          example: equals
        value:
          type: string
          description: Condition value
          example: Hair
      type: object
    ProductDto:
      properties:
        body_html:
          type: string
          description: A description of the product. Supports HTML formatting.
          example: '<p>It''s the small iPod with a big idea: Video.<p>'
        can_preview:
          type: boolean
          description: This product can be previewed by personalize tool or not
        collection_ids:
          items:
            type: integer
          type: array
        created_at:
          type: integer
          description: Created at time
        custom_options:
          items:
            $ref: '#/components/schemas/dto.CustomOption'
          type: array
        display_options:
          $ref: '#/components/schemas/DisplayOptions'
        fulfillment_services:
          items:
            $ref: '#/components/schemas/FulfillmentService'
          type: array
        handle:
          type: string
          description: A unique human-friendly string for the product. Automatically generated from the product's `title`. Used by the Liquid templating language to refer to objects.
          example: ipod-nano-8gb
        id:
          type: integer
          description: A unique numeric identifier for the product. Each id is unique across the ShopBase system. No two products will have the same id, even if they're from different shops.
          example: 632910392
        image:
          $ref: '#/components/schemas/gitlab.ProductImage'
        images:
          items:
            $ref: '#/components/schemas/gitlab.ProductImage'
          type: array
        metafields_global_description_tag:
          type: string
          description: A description of the product used for SEO purposes. Generally added to the <meta name='description'> tag.
          example: 'It''s the small iPod with a big idea: Video.'
        metafields_global_title_tag:
          type: string
          description: The name of the product used for SEO purposes. Generally added to the  <meta name='title'> tag.
          example: IPod Nano - White, 8GB
        options:
          items:
            $ref: '#/components/schemas/dto.ProductOption'
          type: array
        product_availability:
          type: integer
          description: '1. Available in all channels

            2. Hide from the sitemap.txt

            3. Hide from online store listing pages (homepage, collection pages, search page,...)

            0. Hide from all channels'
          example: 7
        product_type:
          type: string
          description: A categorization for the product used for filtering and searching products.
          example: Cult Products
        published:
          type: boolean
          description: Published or not
          example: true
        published_at:
          type: integer
          description: The date and time (ISO 8601 format) when the product was published. Can be set to null to unpublish the product from the Online Store channel.
        tags:
          type: string
          description: A string of comma-separated tags that are used for filtering and search. A product can have up to 250 tags. Each tag can have up to 255 characters.
          example: Emotive, Flash Memory, MP3, Music
        title:
          type: string
          description: The name of the product.
          example: IPod Nano - 8GB
        updated_at:
          type: integer
          description: Updated at time
        variants:
          items:
            $ref: '#/components/schemas/ProductVariantRequestWithOptionValueDto'
          type: array
        vendor:
          type: string
          description: The name of the product's vendor.
          example: Apple
      type: object
    ProductSwaggerResponse:
      properties:
        product:
          $ref: '#/components/schemas/ProductDto'
      type: object
    dto.CustomOption:
      properties:
        active:
          type: boolean
          description: Check whether option is active or not
          example: true
        default_value:
          type: string
          description: Prefill on storefront
          example: default value
        default_value_index:
          type: integer
          description: Index of default value in list values
          example: 1
        font_family:
          type: string
          description: Custom font family style
          example: arial
        font_path:
          type: string
          description: Path to font resource
          example: https://example.com/font_path.tff
        help_text:
          type: string
          description: Custom help text
          example: example
        id:
          type: string
          description: Custom option ID
          example: '123443'
        label:
          type: string
          description: Custom label, displayed on storefront
          example: example label
        layer_name:
          type: string
          description: Layer name
        name:
          type: string
          description: Custom name
          example: example name
        placeholder:
          type: string
          description: Custom placeholder
          example: example
        rules:
          items:
            $ref: '#/components/schemas/dto.Rule'
          type: array
          description: This fields is in progress...
        type:
          type: string
          description: 'Custom type

            </br>**text**: Text field type

            </br>**textarea**: Text area type

            </br>**file**: File type

            </br>**radio**: Radio type

            </br>**select**: Select type

            </br>**checkbox**: Checkbox type

            </br>**picture**: Picture type'
          example: text
        validations:
          $ref: '#/components/schemas/dto.CustomOptionValidations'
          description: List validations
        values:
          items:
            $ref: '#/components/schemas/dto.CustomOptionValue'
          type: array
          description: List option value
      type: object
    ProductVariantRequestWithOptionValueDto:
      properties:
        barcode:
          type: string
          description: The code of variant for easy managing
          example: 9 788073 400972
        body_html:
          type: string
        compare_at_price:
          type: number
          description: The price compare with
          example: 200
        cost_per_item:
          type: number
        fulfillment_service:
          type: string
          description: The name of fulfillment
          example: Shop base fulfillment
        id:
          type: integer
          description: A unique numeric identifier for the product variant. Each id is unique across the ShopBase system. No two products variant will have the same id, even if they're from different shops.
          example: 632910392
        image_id:
          type: integer
          description: The unique numeric identifier for a product's image. The image must be associated to the same product as the variant.
          example: 434522
        image_ids:
          type: string
        inventory_management:
          type: string
          description: The name of inventory management
          example: shopbase
        inventory_policy:
          type: string
          description: 'Whether customers are allowed to place an order for the product variant when it''s out of stock. Valid values

            * **deny**:  Customers are not allowed to place orders for the product variant if it''s out of stock

            * **continue**:  Customers are allowed to place orders for the product variant if it''s out of stock.'
        inventory_quantity:
          type: integer
          description: The quantity in inventory.
          example: 100
        is_default:
          type: boolean
          description: Option to decide that this variant is default or not
          example: true
        metafields:
          items:
            $ref: '#/components/schemas/MetaField'
          type: array
        option1:
          type: string
          description: A unique identifier for the product variant in the shop. Required in order to connect to a FulfillmentService
          example: IPOD2008PINK
        position:
          type: integer
          description: The position of variant.
          example: 1
        price:
          type: number
          description: The price of variant.
          example: 100
        product_id:
          type: integer
          description: A unique numeric identifier for the product. Each id is unique across the ShopBase system. No two products will have the same id, even if they're from different shops.
          example: 632910392
        requires_shipping:
          type: boolean
          description: Whether a customer needs to provide a shipping address when placing an order for the product variant.
          example: true
        sku:
          type: string
          description: The Metafield resource allows you to add additional information to other Admin API resources. Present, we don't use this field. We use table metafield instead.
          example: 'null'
        sync_cache_time:
          type: integer
        taxable:
          type: boolean
          description: Whether a tax is charged when the product variant is sold.
          example: true
        title:
          type: string
          description: The name of the product.
          example: IPod Nano - 8GB
        updated_at:
          type: integer
        weight:
          type: number
          description: Weight of product
          example: 12
        weight_unit:
          type: string
          description: unit of weight
          example: '12'
      type: object
    ProductReorderOptionItem:
      properties:
        id:
          type: integer
          description: Id of product option set
          example: 100
        values:
          items:
            type: string
          type: array
          description: List of product option value.
          example:
          - Red
          - ' Blue'
          - ' Green'
      type: object
    dto.ProductOption:
      properties:
        id:
          type: integer
          description: Id of product option set
          example: 1002
        name:
          type: string
          description: Name of product option set
          example: color
        position:
          type: integer
          description: The order of the product image in the list. The first product image is at position 1 and is the main image for the product.
          example: 1
        product_id:
          type: integer
          description: The id of the product associated with the image.
          example: 632910392
        values:
          items:
            type: string
          type: array
          description: List of product option
          example:
          - red
          - ' blue'
          - ' green'
      type: object
    APIResponseProductTagsDto:
      properties:
        success:
          type: boolean
          description: This field is request api success
          example: true
        tags:
          items:
            type: string
          type: array
          description: This field is request api success
          example:
          - tag1
          - tag2
          - tag3
      type: object
    ProductsSwaggerResponse:
      properties:
        products:
          items:
            $ref: '#/components/schemas/ProductDto'
          type: array
      type: object
    ProductVariantDuplicateResponseSwagger:
      properties:
        fail:
          items:
            type: integer
          type: array
          description: List of variant id duplicate failure
          example:
          - 100013905
        status:
          type: boolean
          description: 'Status of duplicate process: true or false'
          example: true
        success:
          items:
            type: integer
          type: array
          description: List of variant id duplicate successful
          example:
          - 100013903
          - 100013904
      type: object
    dto.CustomOptionValidations:
      properties:
        allowed_characters:
          items:
            type: string
          type: array
          description: 'List character is allowed

            </br>**characters**: Characters

            </br>**numbers**: Numbers

            </br>**symbol**: Special characters

            </br>**emoji**: Emoji'
          example:
          - symbol
        max_length:
          type: integer
          description: Maximum length
          example: 50
        min_size:
          type: number
          description: Maximum size
          example: 50
        required:
          type: boolean
          description: Check whether value is required or not
          example: true
      type: object
    ProductPatchRequest:
      properties:
        count_retry:
          type: integer
        data:
          $ref: '#/components/schemas/ProductPatchFields'
        dest_shop_id:
          type: integer
        exclude_ids:
          items:
            type: integer
          type: array
        has_custom_option:
          type: string
        has_image:
          type: string
        ids:
          items:
            type: integer
          type: array
        keep_current_product_id:
          type: boolean
        page:
          type: integer
        published_status:
          type: string
        shop_id:
          type: integer
        title:
          type: string
        title_mode:
          type: string
        type:
          type: string
      type: object
    ProductPatchFields:
      properties:
        add_collections:
          items:
            type: integer
          type: array
        add_tags:
          items:
            type: string
          type: array
        import_progress:
          items:
            type: string
          type: array
        published:
          type: boolean
        remove_collections:
          items:
            type: integer
          type: array
        remove_tags:
          items:
            type: string
          type: array
      type: object
    ProductDtoSwagger:
      properties:
        body_html:
          type: string
          description: A description of the product. Supports HTML formatting.
          example: '<p>It''s the small iPod with a big idea: Video.<p>'
        custom_options:
          items:
            $ref: '#/components/schemas/dto.CustomOption'
          type: array
          description: List of custom options
        display_options:
          $ref: '#/components/schemas/DisplayOptions'
          description: List of display options
        handle:
          type: string
          description: A unique human-friendly string for the product. Automatically generated from the product's `title`. Used by the Liquid templating language to refer to objects.
          example: ipod-nano-8gb
        images:
          items:
            $ref: '#/components/schemas/dto.ImageRequest'
          type: array
          description: List of images
        metafields_global_description_tag:
          type: string
          description: A description of the product used for SEO purpose

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