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

# Bulk Patch Products

> Update existing products by item_id with independent partial changes.

Omitted fields stay unchanged; zero/false are preserved. Null clears nullable
fields, but sku/sku_name cannot be null or blank. Custom fields merge by normalized
key; a null value clears that key, custom_fields=null clears all values, and {} is a no-op.
Every occurrence of a duplicate trimmed item_id fails with conflict.
HTTP 200 contains ordered indexed success/not_found/validation_error/conflict results.
At most 10,000 items, 25 MiB actual body bytes, and 1 MiB encoded provider request per item.
Writes commit in sequential chunks of at most 500 items; the request is not atomic.
Retry corrected failed entries. After timeout or unknown completion, absolute changes
can be replayed safely (updated_at may advance); reread if intervening writers matter.
Honor Retry-After for 429/503. Missing products are never created and item_id cannot be renamed.
Existing POST bulk and single-product PATCH contracts are unchanged.



## OpenAPI

````yaml https://clientapi.retailgrid.io/openapi.json patch /v1/products/bulk
openapi: 3.1.0
info:
  title: Retailgrid Public API
  version: v1
servers: []
security: []
paths:
  /v1/products/bulk:
    patch:
      tags:
        - products
      summary: Bulk Patch Products
      description: >-
        Update existing products by item_id with independent partial changes.


        Omitted fields stay unchanged; zero/false are preserved. Null clears
        nullable

        fields, but sku/sku_name cannot be null or blank. Custom fields merge by
        normalized

        key; a null value clears that key, custom_fields=null clears all values,
        and {} is a no-op.

        Every occurrence of a duplicate trimmed item_id fails with conflict.

        HTTP 200 contains ordered indexed
        success/not_found/validation_error/conflict results.

        At most 10,000 items, 25 MiB actual body bytes, and 1 MiB encoded
        provider request per item.

        Writes commit in sequential chunks of at most 500 items; the request is
        not atomic.

        Retry corrected failed entries. After timeout or unknown completion,
        absolute changes

        can be replayed safely (updated_at may advance); reread if intervening
        writers matter.

        Honor Retry-After for 429/503. Missing products are never created and
        item_id cannot be renamed.

        Existing POST bulk and single-product PATCH contracts are unchanged.
      operationId: bulk_patch_products_v1_products_bulk_patch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductBatchPatchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductBatchPatchResponse'
        '413':
          description: More than 10,000 rows or 25 MiB
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ProductBatchPatchRequest:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ProductBatchPatchItem'
          type: array
          maxItems: 10000
          title: Items
          description: >-
            At most 10,000 entries and 25 MiB actual body bytes. Invalid entries
            fail independently.
      additionalProperties: false
      type: object
      required:
        - items
      title: ProductBatchPatchRequest
      examples:
        - items:
            - current_price: 0
              item_id: price
            - item_id: supplier
              supplier: New supplier
            - custom_fields:
                featured: false
              item_id: custom
            - item_id: clear
            - current_price: 5
              item_id: missing
            - item_id: invalid
            - current_price: 10
              item_id: duplicate
            - item_id: duplicate
              supplier: Other supplier
    ProductBatchPatchResponse:
      properties:
        results:
          items:
            oneOf:
              - $ref: '#/components/schemas/ProductBatchPatchSuccess'
              - $ref: '#/components/schemas/ProductBatchPatchError'
            discriminator:
              propertyName: ok
              mapping:
                'False': '#/components/schemas/ProductBatchPatchError'
                'True': '#/components/schemas/ProductBatchPatchSuccess'
          type: array
          title: Results
      type: object
      title: ProductBatchPatchResponse
      examples:
        - results:
            - id: 00000000-0000-4000-8000-000000000001
              index: 0
              ok: true
            - id: 00000000-0000-4000-8000-000000000002
              index: 1
              ok: true
            - id: 00000000-0000-4000-8000-000000000003
              index: 2
              ok: true
            - id: 00000000-0000-4000-8000-000000000004
              index: 3
              ok: true
            - code: not_found
              index: 4
              message: Product not found
              ok: false
            - code: validation_error
              index: 5
              message: sku cannot be null or blank
              ok: false
            - code: conflict
              index: 6
              message: Duplicate item_id in this batch
              ok: false
            - code: conflict
              index: 7
              message: Duplicate item_id in this batch
              ok: false
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ProductBatchPatchItem:
      properties:
        product_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Id
        product_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Name
        product_group:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Group
        manufacturer:
          anyOf:
            - type: string
            - type: 'null'
          title: Manufacturer
        long_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Long Description
        supplier:
          anyOf:
            - type: string
            - type: 'null'
          title: Supplier
        manufacturer_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Manufacturer Code
        supplier_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Supplier Code
        brand:
          anyOf:
            - type: string
            - type: 'null'
          title: Brand
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
        product_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Type
        barcode:
          anyOf:
            - type: string
            - type: 'null'
          title: Barcode
        stock_on_hand:
          anyOf:
            - type: number
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Stock On Hand
        category_1:
          anyOf:
            - type: string
            - type: 'null'
          title: Category 1
        category_2:
          anyOf:
            - type: string
            - type: 'null'
          title: Category 2
        category_3:
          anyOf:
            - type: string
            - type: 'null'
          title: Category 3
        category_4:
          anyOf:
            - type: string
            - type: 'null'
          title: Category 4
        category_5:
          anyOf:
            - type: string
            - type: 'null'
          title: Category 5
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
        product_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Url
        rrp:
          anyOf:
            - type: number
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Rrp
        regular_price:
          anyOf:
            - type: number
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Regular Price
        product_created_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Product Created Date
        price_effective_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Price Effective Date
        cost_effective_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Cost Effective Date
        size:
          anyOf:
            - type: string
            - type: 'null'
          title: Size
        color:
          anyOf:
            - type: string
            - type: 'null'
          title: Color
        uom:
          anyOf:
            - type: string
            - type: 'null'
          title: Uom
        tax_rate:
          anyOf:
            - type: number
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Tax Rate
        currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency
        custom_fields:
          anyOf:
            - additionalProperties:
                anyOf:
                  - type: string
                  - type: number
                  - type: string
                    pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
                  - type: string
                    format: date
                  - type: string
                    format: date-time
                  - type: boolean
                  - type: 'null'
              type: object
            - type: 'null'
          title: Custom Fields
        item_id:
          type: string
          minLength: 1
          title: Item Id
          description: Organization-scoped business identity; whitespace is trimmed.
        sku:
          anyOf:
            - type: string
            - type: 'null'
          title: Sku
        sku_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Sku Name
        current_price:
          anyOf:
            - type: number
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Current Price
        unit_cost:
          anyOf:
            - type: number
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Unit Cost
      additionalProperties: false
      type: object
      required:
        - item_id
      title: ProductBatchPatchItem
      description: item_id selects an existing product; only supplied fields change.
    ProductBatchPatchSuccess:
      properties:
        index:
          type: integer
          title: Index
        ok:
          type: boolean
          const: true
          title: Ok
          default: true
        id:
          type: string
          format: uuid
          title: Id
      type: object
      required:
        - index
        - id
      title: ProductBatchPatchSuccess
    ProductBatchPatchError:
      properties:
        index:
          type: integer
          title: Index
        ok:
          type: boolean
          const: false
          title: Ok
          default: false
        code:
          type: string
          enum:
            - validation_error
            - conflict
            - not_found
          title: Code
        message:
          type: string
          maxLength: 512
          title: Message
      type: object
      required:
        - index
        - code
        - message
      title: ProductBatchPatchError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````

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