> ## Documentation Index
> Fetch the complete documentation index at: https://quickbutik.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get products

> Fetch products in store with optional filtering. When no specific product_id or sku is provided,
the following filters can be used to search and filter products.

**Important - Response Structure Varies:**
- When using the `search` parameter: Returns a direct array `[...]`
- When NOT using the `search` parameter: Returns `{product: [...]}`
- When requesting a specific product by `product_id` or `sku`: Returns `{product: {...}}`




## OpenAPI

````yaml get /v1/products
openapi: 3.1.0
info:
  title: Quickbutik API
  version: 1.0.0
  description: >-
    Use the Quickbutik API to access and manage stores, products, orders, and
    more.
  contact:
    name: Quickbutik API Support
    url: https://quickbutik.com/support
  license:
    name: Proprietary
  x-fiddle-import-file: true
servers:
  - url: https://api.quickbutik.com
    description: Production server
security:
  - BasicAuth: []
tags:
  - name: Orders
    description: Order management operations
  - name: Products
    description: Product catalog management
  - name: Categories
    description: Product category management
  - name: Payment Methods
    description: Available payment methods
  - name: Shipping Methods
    description: Available shipping methods
  - name: Metadata
    description: Custom metadata management
  - name: Settings
    description: Store settings and configuration
  - name: Scripts
    description: Storefront script management
paths:
  /v1/products:
    get:
      tags:
        - Products
      summary: Get products
      description: >
        Fetch products in store with optional filtering. When no specific
        product_id or sku is provided,

        the following filters can be used to search and filter products.


        **Important - Response Structure Varies:**

        - When using the `search` parameter: Returns a direct array `[...]`

        - When NOT using the `search` parameter: Returns `{product: [...]}`

        - When requesting a specific product by `product_id` or `sku`: Returns
        `{product: {...}}`
      operationId: get-products
      parameters:
        - name: product_id
          in: query
          description: >-
            Product ID(s) to fetch. Can be a single ID or comma-separated list
            of IDs
          schema:
            type: string
            example: 123,456,789
        - name: sku
          in: query
          description: >-
            Product SKU(s) to fetch. Can be a single SKU or comma-separated list
            of SKUs
          schema:
            type: string
            example: T-SHIRT-123,HOODIE-456
        - name: search
          in: query
          description: >
            Search products by title, description, SKU, or variant SKU.

            **Note:** When this parameter is used, the response returns a direct
            array instead of the usual `{product: [...]}` wrapper.
          schema:
            type: string
            example: cotton t-shirt
        - name: categories
          in: query
          description: >-
            Filter products by category ID(s). Can be a single ID or
            comma-separated list of IDs
          schema:
            type: string
            example: 1,2,3
        - name: visibility
          in: query
          description: Filter products by visibility status
          schema:
            type: boolean
            example: true
        - name: is_giftcard
          in: query
          description: >
            Find products that are gift cards. When set to `true`, only gift
            card products are returned. When set to `false`, gift card products
            are excluded.


            **Note:** This parameter only works when the gift card app is active
            for the shop. If the app is not active, this parameter is ignored.
          schema:
            type: boolean
            example: true
        - name: from_date_modified
          in: query
          description: Filter products modified since this date (UNIX timestamp)
          schema:
            type: integer
            example: 1596097247
        - name: order_by
          in: query
          description: Field to sort products by
          schema:
            type: string
            enum:
              - id
              - title
              - price
              - qty
              - sku
              - visits
              - purchase_price
            default: id
        - name: sort_order
          in: query
          description: Sort direction
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/IncludeDetails'
      responses:
        '200':
          $ref: '#/components/responses/ProductsSuccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ProductNotFound'
components:
  parameters:
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
      description: >-
        The maximum number of rows returned. The default is 100, and the value
        may not exceed 500
    Offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
      description: >-
        The amount of rows to skip before returning. This can be used to loop
        through all objects if there are more than the limit allows to be
        returned
    IncludeDetails:
      name: include_details
      in: query
      schema:
        type: boolean
      description: >-
        Indicates whether or not details are returned. When true, includes
        additional information such as images, categories, metadata, and product
        package components for bundled products. Default is false for multiple
        items, true for single items
  responses:
    ProductsSuccess:
      description: Product(s) retrieved successfully
      content:
        application/json:
          schema:
            oneOf:
              - type: object
                properties:
                  product:
                    oneOf:
                      - $ref: '#/components/schemas/Product'
                      - type: array
                        items:
                          $ref: '#/components/schemas/Product'
                description: >-
                  Response structure when fetching by product_id/sku or without
                  search parameter. Returns object with 'product' key containing
                  either a single product or array of products.
              - type: array
                items:
                  $ref: '#/components/schemas/Product'
                description: >-
                  Response structure when using the 'search' parameter. Returns
                  a direct array of products.
    Unauthorized:
      description: Unauthorized - Invalid or missing authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ProductNotFound:
      description: >-
        Product/s could not be found or no products match the search criteria.
        Note that empty search results return 404 rather than 200 with an empty
        array.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Product:
      type: object
      properties:
        id:
          type: string
          example: '12'
        sku:
          type: string
          example: BBB222
        hasVariants:
          type: string
          example: '1'
        title:
          type: string
          example: VITA Ljus lampskärm
        visible:
          type: string
          example: '1'
        qty:
          type:
            - string
            - 'null'
        price:
          type: string
          example: '899'
        purchase_price:
          type:
            - string
            - 'null'
        before_price:
          type:
            - string
            - 'null'
        description:
          type: string
        seo_title:
          type:
            - string
            - 'null'
        seo_description:
          type:
            - string
            - 'null'
        weight:
          type: string
          example: '0'
        gtin:
          type: string
        date_modified:
          type: string
          example: '2017-09-27 10:29:22'
        variants:
          type: array
          description: >-
            Product variants. Only included when include_details=true and the
            product has variants (hasVariants='1').
          items:
            $ref: '#/components/schemas/ProductVariantResponse'
        preorder:
          type:
            - integer
            - 'null'
          description: >-
            ID of the preorder option assigned to this product/variant, or null
            if not a preorder. Use GET /v1/settings/preorders to retrieve
            available option IDs.
          example: 1
        is_giftcard:
          type: boolean
          description: >-
            Whether this product is a gift card. Only included when the gift
            card feature is active for the shop.
          example: false
        product_package_products:
          type: array
          description: >-
            Product package components. Only included when include_details=true
            and the product is a package containing other products.
          items:
            $ref: '#/components/schemas/ProductPackageComponent'
    Error:
      type: object
      properties:
        code:
          type: integer
          example: 404
        error:
          type: string
          example: Resource not found
    ProductVariantResponse:
      type: object
      description: >-
        Variant structure returned by GET requests when include_details=true.
        Note that this differs from the input format used for creating/updating
        variants.
      properties:
        id:
          type: string
          description: Variant ID
          example: '1058'
        ovalue_id_1:
          type: string
          description: Option value ID reference
          example: '987'
        product_id:
          type: string
          description: Parent product ID
          example: '2436'
        sku:
          type: string
          description: Variant SKU
          example: Grönd
        price:
          type: string
          description: Variant price
          example: '200.00'
        qty:
          type:
            - string
            - 'null'
          description: Stock quantity
        weight:
          type:
            - string
            - 'null'
          description: Variant weight
        before_price:
          type:
            - string
            - 'null'
          description: Compare price
        purchase_price:
          type:
            - string
            - 'null'
          description: Purchase price
        image_id:
          type:
            - string
            - 'null'
          description: Associated image ID
        gtin:
          type:
            - string
            - 'null'
          description: GTIN/EAN code
        supplier_sku:
          type:
            - string
            - 'null'
          description: Supplier SKU
        hidden:
          type:
            - string
            - 'null'
          description: Hidden status
        qty_location:
          type: string
          description: Stock location
          example: ''
        preorder:
          type:
            - string
            - 'null'
          description: Preorder status
        min_purchase_quantity:
          type:
            - string
            - 'null'
          description: Minimum purchase quantity
        max_purchase_quantity:
          type:
            - string
            - 'null'
          description: Maximum purchase quantity
        preselected:
          type:
            - string
            - 'null'
          description: Preselected status
        disable_minusqty:
          type: boolean
          description: Disable negative stock
          example: true
        values:
          type: array
          description: >-
            Array of variant option values. Each object represents one option
            dimension (Color, Size, etc.)
          items:
            type: object
            properties:
              ovalue_field:
                type: string
                description: Option value field reference
                example: '987'
              name:
                type: string
                description: Option name (e.g., "Color", "Size", "Färg"). May be localized.
                example: Färg
              val:
                type: string
                description: Option value (e.g., "Red", "Large", "Grön")
                example: Grön " 32 size
    ProductPackageComponent:
      type: object
      description: Represents a component product within a product package
      properties:
        product_id:
          type: integer
          description: ID of the component product
          example: 456
        variant_id:
          type:
            - integer
            - 'null'
          description: Variant ID of the component product (null if no variant)
          example: 789
        title:
          type: string
          description: Title of the component product
          example: T-shirt Red
        variant:
          type:
            - string
            - 'null'
          description: Variant name (null if no variant)
          example: Large
        qty:
          type: integer
          description: Quantity of this component in the package
          example: 2
        sku:
          type: string
          description: SKU of the component product/variant
          example: TSHIRT-RED-L
        price:
          type: string
          description: Price of the component product/variant
          example: '299'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >
        **Basic Authentication with API Keys**


        The Quickbutik API uses Basic Authentication where you use your API key
        as both the username and password.


        **How it works:**

        1. Format your credentials as `api_key:api_key` (using the SAME API key
        for both username and password)

        2. Base64 encode the formatted string

        3. Include in the Authorization header as: `Authorization: Basic
        ENCODED_STRING`


        **Example:**

        - API Key: `sk_live_abc123`

        - Formatted: `sk_live_abc123:sk_live_abc123`

        - Base64 Encoded: `c2tfbGl2ZV9hYmMxMjM6c2tfbGl2ZV9hYmMxMjM=`

        - Header: `Authorization: Basic
        c2tfbGl2ZV9hYmMxMjM6c2tfbGl2ZV9hYmMxMjM=`


        **cURL Example:**

        ```bash

        curl https://api.quickbutik.com/v1/orders -u your_api_key:your_api_key

        ```


        All API requests must be made over HTTPS. Requests made over HTTP will
        be rejected.


        API keys can be generated in the Quickbutik Control Panel under Settings
        → API.

````