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

# Bulk Upsert Products

> Creates or updates up to 100 flat product variants in one call. A variant is matched by id or reference_id (reference_id defaults to sku_id). Variants sharing a group_code form one product family. Returns 200 with one result per item (status success/error) and meta totals; check each item's status.



## OpenAPI

````yaml post /v1/products/bulk
openapi: 3.1.0
info:
  description: Client-facing Open APIs for WizCommerce
  title: WizCommerce Open API's
  termsOfService: https://wizcommerce.com/terms/
  contact:
    name: Tech Support
    url: https://help.wizcommerce.com/
    email: tech@wizcommerce.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: '1.0'
servers:
  - url: https://api.wizcommerce.com
    description: Production BaseURL
  - url: https://api-staging.sourcerer.tech
    description: Staging BaseURL
security: []
paths:
  /v1/products/bulk:
    post:
      tags:
        - Product
      summary: Bulk Upsert Products
      description: >-
        Creates or updates up to 100 flat product variants in one call. A
        variant is matched by id or reference_id (reference_id defaults to
        sku_id). Variants sharing a group_code form one product family. Returns
        200 with one result per item (status success/error) and meta totals;
        check each item's status.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bulkdto.BulkProductRequest'
        description: 1-100 items; body must not exceed 10 MiB
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bulkdto.BulkProductResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.HttpError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.HttpError'
        '413':
          description: Request Entity Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.HttpError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.HttpError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.HttpError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.HttpError'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.HttpError'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.HttpError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    bulkdto.BulkProductRequest:
      type: object
      required:
        - data
      properties:
        data:
          description: >-
            1-100 variants. reference_id and id must be unique within the batch.
            Body must not exceed 10 MiB.
          type: array
          maxItems: 100
          minItems: 1
          items:
            $ref: '#/components/schemas/bulkdto.BulkProduct'
    bulkdto.BulkProductResponse:
      type: object
      properties:
        data:
          description: One result per request item, in request order.
          type: array
          items:
            $ref: '#/components/schemas/bulkdto.BulkProductResult'
          x-order: '1'
        meta:
          allOf:
            - $ref: '#/components/schemas/bulkdto.BulkProductMeta'
          x-order: '2'
    errors.HttpError:
      type: object
      properties:
        code:
          type: string
          x-order: '1'
        message:
          type: string
          x-order: '2'
        details:
          type: array
          items:
            $ref: '#/components/schemas/errors.HttpErrorDetails'
          x-order: '3'
    bulkdto.BulkProduct:
      type: object
      required:
        - name
        - sku_id
      properties:
        id:
          description: Existing variant id (UUID).
          type: string
          x-order: '1'
          example: 01f5d171-d3e3-4b2b-bd57-0727194b5bed
        reference_id:
          description: >-
            Your system's id. Defaults to sku_id when omitted, so re-sending the
            same sku updates it.
          type: string
          x-order: '2'
          example: CUSH-RED-18
        sku_id:
          type: string
          x-order: '3'
          example: CUSH-RED-18
        name:
          type: string
          x-order: '4'
          example: Velvet Cushion Red 18in
        group_code:
          description: >-
            Family key. Variants with the same group_code are grouped; defaults
            to sku_id.
          type: string
          x-order: '5'
          example: CUSH-VELVET-18
        keep_existing_group:
          description: >-
            When group_code is omitted on update, keep the variant in its
            current family.
          type: boolean
          x-order: '6'
          example: false
        is_primary:
          description: Primary variant of the family.
          type: boolean
          x-order: '7'
          example: true
        priority:
          type: integer
          x-order: '8'
          example: 1
        status:
          type: string
          enum:
            - active
            - inactive
          x-order: '9'
          example: active
        brand:
          type: string
          x-order: '10'
          example: Auralane
        grouping_attributes:
          description: Attribute names that distinguish variants in the family, in order.
          type: array
          items:
            type: string
          x-order: '11'
          example:
            - Color
            - Size
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/bulkdto.BulkProductAttribute'
          x-order: '12'
        hinge_values:
          description: Derived from grouping_attributes + attributes when omitted.
          type: object
          additionalProperties: true
          x-order: '13'
        categories:
          description: Category paths or ids.
          type: array
          items:
            type: string
          x-order: '14'
          example:
            - Home Decor/Cushions
        collections:
          type: array
          items:
            type: string
          x-order: '15'
          example:
            - Winter 2026
        tags:
          type: array
          items:
            type: string
          x-order: '16'
          example:
            - velvet
            - bestseller
        product_prices:
          description: One entry per price list; price lists must be unique.
          type: array
          items:
            $ref: '#/components/schemas/bulkdto.BulkProductPrice'
          x-order: '17'
        medias:
          type: array
          items:
            $ref: '#/components/schemas/bulkdto.BulkProductMedia'
          x-order: '18'
        url_slug:
          type: string
          x-order: '19'
          example: velvet-cushion-red-18
        seo_info:
          allOf:
            - $ref: '#/components/schemas/bulkdto.BulkProductSeo'
          x-order: '20'
        channel_visibility:
          allOf:
            - $ref: '#/components/schemas/bulkdto.BulkProductChannelVisibility'
          x-order: '21'
        volume:
          allOf:
            - $ref: '#/components/schemas/bulkdto.BulkProductVolume'
          x-order: '22'
    bulkdto.BulkProductResult:
      type: object
      properties:
        index:
          description: Position in the request data array.
          type: integer
          x-order: '1'
          example: 0
        status:
          type: string
          enum:
            - success
            - error
          x-order: '2'
          example: success
        id:
          type: string
          x-order: '3'
          example: 01f5d171-d3e3-4b2b-bd57-0727194b5bed
        parent_id:
          description: Product family id.
          type: string
          x-order: '4'
          example: 8e7d6c5b-4a39-4b2c-a1d0-f9e8d7c6b5a4
        reference_id:
          type: string
          x-order: '5'
          example: CUSH-RED-18
        sku_id:
          type: string
          x-order: '6'
          example: CUSH-RED-18
        group_code:
          type: string
          x-order: '7'
          example: CUSH-VELVET-18
        action:
          description: null when status is error.
          type: string
          enum:
            - create
            - update
          x-order: '8'
          example: create
        indexed:
          type: boolean
          x-order: '9'
          example: true
        error:
          description: null when status is success.
          allOf:
            - $ref: '#/components/schemas/bulkdto.BulkItemError'
          x-order: '10'
        mapping_errors:
          description: >-
            Written, but some links failed, keyed by field (e.g. pricing_ok,
            categories_ok).
          type: object
          additionalProperties:
            $ref: '#/components/schemas/bulkdto.BulkItemError'
          x-order: '11'
    bulkdto.BulkProductMeta:
      type: object
      properties:
        total:
          type: integer
          x-order: '1'
          example: 2
        success:
          type: integer
          x-order: '2'
          example: 2
        failed:
          type: integer
          x-order: '3'
          example: 0
    errors.HttpErrorDetails:
      type: object
      properties:
        field:
          type: string
          x-order: '1'
        reason:
          type: string
          x-order: '2'
    bulkdto.BulkProductAttribute:
      type: object
      properties:
        id:
          type: string
          x-order: '1'
          example: 3f1c2b9e-7a1d-4c55-9a0e-2f8d6b1c4e21
        name:
          type: string
          x-order: '2'
          example: Color
        value:
          description: Any JSON value (string, number, boolean or list), e.g. "Red".
          x-order: '3'
    bulkdto.BulkProductPrice:
      type: object
      required:
        - price
      properties:
        price_list_id:
          description: Price list UUID. Send price_list_id or reference_id.
          type: string
          x-order: '2'
          example: 9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
        reference_id:
          description: Price list reference id.
          type: string
          x-order: '3'
          example: WHOLESALE
        price:
          type: number
          x-order: '4'
          example: 24.99
        sale_price:
          type: number
          x-order: '6'
          example: 19.99
        min_order_quantity:
          type: integer
          default: 1
          x-order: '7'
          example: 1
        step_increment:
          type: integer
          default: 1
          x-order: '8'
          example: 1
        max_order_quantity:
          type: integer
          default: 99999
          x-order: '9'
          example: 99999
        default_order_quantity:
          type: integer
          x-order: '10'
          example: 6
        volume_tiers:
          type: array
          items:
            $ref: '#/components/schemas/bulkdto.BulkProductVolumeTier'
          x-order: '11'
    bulkdto.BulkProductMedia:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          x-order: '1'
          example: https://cdn.example.com/cushion-red.jpg
        type:
          type: string
          default: image
          x-order: '2'
          example: image
        order:
          type: integer
          x-order: '3'
          example: 1
        is_default:
          type: boolean
          x-order: '4'
          example: true
    bulkdto.BulkProductSeo:
      type: object
      properties:
        primary_title:
          type: string
          x-order: '1'
          example: Velvet Cushion
        title:
          type: string
          x-order: '2'
          example: Velvet Cushion Red 18in | Auralane
        description:
          type: string
          x-order: '3'
          example: Soft velvet cushion cover with insert.
        keywords:
          type: array
          items:
            type: string
          x-order: '4'
          example:
            - cushion
            - velvet
    bulkdto.BulkProductChannelVisibility:
      type: object
      properties:
        website:
          type: string
          enum:
            - DontShow
            - ShowForLoggedInUsersOnly
            - ShowForLoggedInAndNonLoggedInUsers
          x-order: '1'
          example: ShowForLoggedInUsersOnly
    bulkdto.BulkProductVolume:
      type: object
      properties:
        cbm:
          type: number
          x-order: '1'
          example: 0.02
        cft:
          type: number
          x-order: '2'
          example: 0.7
    bulkdto.BulkItemError:
      type: object
      properties:
        code:
          type: string
          enum:
            - VALIDATION_ERROR
            - NOT_FOUND
            - CATEGORY_NOT_FOUND
            - COLLECTION_NOT_FOUND
            - CATALOG_NOT_FOUND
            - ATTRIBUTE_NOT_FOUND
            - REFERENCE_CONFLICT
            - INTERNAL_ERROR
          x-order: '1'
          example: NOT_FOUND
        message:
          type: string
          x-order: '2'
          example: Category 'Bedding/Cushions' not found
    bulkdto.BulkProductVolumeTier:
      type: object
      required:
        - price
        - start_quantity
      properties:
        start_quantity:
          description: 1-99999
          type: integer
          x-order: '1'
          example: 12
        price:
          type: number
          x-order: '2'
          example: 21.99
        step_increment:
          type: integer
          default: 1
          x-order: '3'
          example: 1
  securitySchemes:
    ApiKeyAuth:
      description: API Key for authentication
      type: apiKey
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.