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

# Update Collection Item (Partial)

> Partially update an existing Collection item via PATCH request, modifying only the specified fields.

Perform a partial update (PATCH) of an existing Collection item, updating only the fields you specify while preserving all other content. This method is ideal for targeted updates without affecting the entire item structure.

**Update Method**: PATCH updates only the fields included in your request body, leaving all other fields unchanged. This differs from PUT operations, which replace the entire item. Use PATCH when you want to modify specific fields while preserving existing content, relationships, and metadata.

**Partial Update Intelligence**: Reference fields, status, timestamps, and any omitted content fields automatically retain their current values. This allows you to safely update specific content without worrying about accidentally clearing other important data.

> **Important**: The URL must include a trailing slash after the item ID (e.g., `/v2/content/my-collection/123/`). This is required for the endpoint to function correctly.

**Item Identification**: The unique item ID can be found in the `meta` field of any collection item when retrieved through GET requests. This identifier remains constant throughout the item's life cycle.

**Reference Field Handling**: When updating reference fields, use page slugs for Page references and item IDs for Collection references. If you omit reference fields from your request, existing references remain completely unchanged, making it safe to update other content without affecting relationships.

**Asynchronous Processing**: This endpoint returns `202 Accepted` immediately to ensure fast response times. The actual update processing, including media uploads, reference validation, and webhook triggers, happens in the background processing queue.


## OpenAPI

````yaml /api/openapi/write_api.yaml patch /content/{collection_key}/{item_id}/
openapi: 3.1.0
info:
  title: ButterCMS Write API
  version: 2.0.0
  description: >
    Write endpoints for the ButterCMS API — create, update, and delete Pages,
    Collections, and Blog Posts.
  contact:
    email: support@buttercms.com
  license:
    name: ButterCMS Terms of Service
    url: https://buttercms.com/terms/
servers:
  - url: https://api.buttercms.com/v2
    description: ButterCMS API v2
security:
  - writeTokenAuth: []
tags:
  - name: Pages
    description: >
      Create new pages using ButterCMS Write API. Programmatically create
      content to enable powerful use cases and scale your content faster.


      Note: For Pages, PUT behaves like PATCH (partial update). Use either
      method to perform partial updates.
  - name: Collections
    description: >
      Create, update, and delete Collection items using ButterCMS Write API.
      Collections are user-defined content structures with completely
      customizable field schemas.
  - name: Blog posts
    description: >
      Create, update, and delete blog posts using ButterCMS Write API. Blog
      posts support rich content including HTML body, categories, tags, featured
      images, and SEO metadata.
paths:
  /content/{collection_key}/{item_id}/:
    patch:
      tags:
        - Collections
      summary: Update Collection Item (Partial)
      description: >
        Perform a partial update (PATCH) of an existing Collection item,
        updating only the fields you specify while preserving all other content.
        This method is ideal for targeted updates without affecting the entire
        item structure.


        **Update Method**: PATCH updates only the fields included in your
        request body, leaving all other fields unchanged. This differs from PUT
        operations, which replace the entire item. Use PATCH when you want to
        modify specific fields while preserving existing content, relationships,
        and metadata.


        **Partial Update Intelligence**: Reference fields, status, timestamps,
        and any omitted content fields automatically retain their current
        values. This allows you to safely update specific content without
        worrying about accidentally clearing other important data.


        > **Important**: The URL must include a trailing slash after the item ID
        (e.g., `/v2/content/my-collection/123/`). This is required for the
        endpoint to function correctly.


        **Item Identification**: The unique item ID can be found in the `meta`
        field of any collection item when retrieved through GET requests. This
        identifier remains constant throughout the item's life cycle.


        **Reference Field Handling**: When updating reference fields, use page
        slugs for Page references and item IDs for Collection references. If you
        omit reference fields from your request, existing references remain
        completely unchanged, making it safe to update other content without
        affecting relationships.


        **Asynchronous Processing**: This endpoint returns `202 Accepted`
        immediately to ensure fast response times. The actual update processing,
        including media uploads, reference validation, and webhook triggers,
        happens in the background processing queue.
      operationId: patchCollectionItem
      parameters:
        - name: collection_key
          in: path
          required: true
          schema:
            type: string
            maxLength: 100
          description: >
            The unique identifier/slug of the Collection containing the item to
            update.


            Must match an existing collection in your organization.
          example: team_members
        - name: item_id
          in: path
          required: true
          schema:
            type: string
            maxLength: 50
          description: >
            The unique identifier of the collection item to update.


            **Important**: The URL must end with a trailing slash after this
            parameter.


            This ID can be found in the `meta` field of collection items
            returned by GET operations.
          example: '123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCollectionItemRequest'
            examples:
              without_locales_partial:
                summary: Partial update without locales
                description: Update only specific fields, others remain unchanged
                value:
                  status: published
                  fields:
                    field2_key: Only this field gets updated
              with_locales_partial:
                summary: Partial update with locales
                description: Update only specific locales and fields
                value:
                  status: published
                  fields:
                    en:
                      field2_key: Updated English field
                    es:
                      field1_key: Campo actualizado en español
              reference_partial_update:
                summary: Partial reference field update
                description: Update only reference relationships, preserve other fields
                value:
                  fields:
                    related_page: new-page-slug
                    tags:
                      - 7
                      - 8
              status_only_update:
                summary: Status change only
                description: Change only the publication status
                value:
                  status: draft
      responses:
        '202':
          $ref: '#/components/responses/CollectionItemAcceptedResponse'
        '400':
          description: Bad Request - Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                validation_errors:
                  summary: Field validation errors
                  value:
                    field1_key:
                      - This field is required.
                    status:
                      - Valid status values are 'draft' and 'published'
                invalid_references:
                  summary: Reference field errors
                  value:
                    related_page:
                      - Page with slug 'nonexistent-page' not found.
                    tags:
                      - Collection item with ID 999 not found.
        '401':
          $ref: f90388ba-d70a-4363-80c0-94f0c4076bc0
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                write_permission:
                  summary: Token lacks write permissions
                  value:
                    detail: Token does not have write permissions
        '404':
          description: Not Found - Collection or item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                collection_not_found:
                  summary: Collection not found
                  value:
                    detail: Collection not found
                item_not_found:
                  summary: Collection item not found
                  value:
                    detail: Collection item not found
      security:
        - writeTokenAuth: []
components:
  schemas:
    UpdateCollectionItemRequest:
      type: object
      description: >
        **Flexible request schema for updating collection items - supports both
        single-locale and multi-locale formats.**


        **Update Types**:

        - **PUT**: Requires `fields` for full replacement

        - **PATCH**: `fields` is optional for partial updates (e.g., status-only
        updates)
      properties:
        status:
          $ref: 60cafcd7-6cdb-4012-a76a-1916542e84d4
          description: |
            Publication status of the collection item.

            - If omitted in PATCH requests, the current status is preserved
            - If provided in PUT/PATCH requests, the status will be updated
        fields:
          type: object
          description: >
            **Optional for PATCH, Required for PUT**. Collection item field data
            with flexible format support.


            System automatically detects the format based on the structure of
            the object:


            **Without Locales Format**: Direct field properties (e.g., `name`,
            `position`, `bio`)

            **With Locales Format**: Locale codes as keys (e.g., `en`, `es`,
            `fr`)


            **Update Behavior**:

            - **PUT**: All fields should be provided (full replacement)

            - **PATCH**: Only provided fields are updated, others remain
            unchanged


            **Dynamic Schema**: Field names and types are completely
            user-defined based on your collection configuration.


            **Reference Fields**: Support updating relationships to Pages and
            other Collections

            - Page references: Use page slugs (e.g., `"related_page":
            "example-slug"`)

            - Collection references: Use collection item IDs (e.g., `"tags": [1,
            2, 3]`)

            - Remove references: Use `""`, `[]`, or `null`


            **Media Fields**: Support remote URL upload - content is
            automatically uploaded to ButterCMS
          additionalProperties: true
          example:
            name: Updated Team Member Name
            position: Lead Developer
            bio: Updated biography content
    ValidationErrorResponse:
      type: object
      description: >-
        Response for validation errors (400 Bad Request) - supports both
        field-specific errors and general error messages
      oneOf:
        - type: object
          description: >-
            Field-specific validation errors (used by Pages, Blog Posts, and
            Collections)
          additionalProperties:
            type: array
            items:
              type: string
          example:
            title:
              - You must specify a page title.
            slug:
              - You must specify a page slug.
        - type: object
          description: General error message (used for organization limits, etc.)
          properties:
            error:
              type: string
              description: Error message
          example:
            error: >-
              Cannot create a new Collection Item. Collection Item Limit
              Reached.
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing what went wrong
          example: Authentication credentials were not provided
  responses:
    CollectionItemAcceptedResponse:
      description: Collection item operation accepted for async processing
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - pending
                description: >-
                  Indicates the request was accepted and is being processed
                  asynchronously
                example: pending
          example:
            status: pending
  securitySchemes:
    writeTokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >
        Write-enabled API token required for creating content.


        The API token you use for reading from the ButterCMS API will not allow
        you to create content in the API. For this you will need to use a
        different write-enabled token. Chat or email support@buttercms.com to
        get yours.


        Set the `Authorization` header to `Token your_write_api_token`.


        Example: `Authorization: Token abc123def456`


        Your write-enabled token should never be used anywhere it would be
        exposed, e.g. in client-side JavaScript.

````