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

# Create, update or delete a collection version's brand features

> Writes one kind of brand feature (content blocks, image settings, product duplicates or the legacy A/B test) for a collection version: upserts `upsert_metaobjects` as Shopify metaobjects (matched by `handle`) and deletes `delete_metaobjects_by_handle`, then records the version's feature list. Side effects: Shopify metaobject writes (live on the storefront for the published version), definition creation on first use, and multi-market expansion. Returns `[]`.



## OpenAPI

````yaml /api-reference/openapi/lite.json put /brand-features/{collection_id}
openapi: 3.1.0
info:
  title: Search & Merchandising API
  version: 1.0.0
  description: >-
    REST API behind Depict: Search & Merchandising, the native Shopify app:
    onboarding, collections, boost & bury, dashboards, A/B testing and
    multi-store management. Endpoints are served under the /api/lite prefix and
    are authenticated with the Shopify session token that App Bridge issues to
    the embedded app.
servers:
  - url: /api/lite
security:
  - ShopifySessionToken: []
paths:
  /brand-features/{collection_id}:
    put:
      summary: Create, update or delete a collection version's brand features
      description: >-
        Writes one kind of brand feature (content blocks, image settings,
        product duplicates or the legacy A/B test) for a collection version:
        upserts `upsert_metaobjects` as Shopify metaobjects (matched by
        `handle`) and deletes `delete_metaobjects_by_handle`, then records the
        version's feature list. Side effects: Shopify metaobject writes (live on
        the storefront for the published version), definition creation on first
        use, and multi-market expansion. Returns `[]`.
      operationId: brandFeatures
      parameters:
        - schema:
            type: string
            description: The Shopify collection id (numeric, no gid prefix).
          required: true
          description: The Shopify collection id (numeric, no gid prefix).
          name: collection_id
          in: path
        - schema:
            type: string
            description: Lite merchant id, e.g. `shopify-<shop id>`.
          required: true
          description: Lite merchant id, e.g. `shopify-<shop id>`.
          name: merchant_id
          in: query
        - schema:
            type: string
            format: uuid
            description: The collection version (UUID) the features belong to.
          required: true
          description: The collection version (UUID) the features belong to.
          name: version
          in: query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandFeatureUpdateRequest'
      responses:
        '200':
          description: Saved; the body is `[]`.
          content:
            application/json:
              schema:
                type: array
                items: {}
                description: Always empty.
        '400':
          description: >-
            The query or body failed the schema, or the merchant has no Shopify
            configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '401':
          description: Not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '403':
          description: Authenticated, but this identity may not call the API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '404':
          description: >-
            Merchant not found for this caller, or the collection has no such
            version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '415':
          description: Content-Type is not application/json.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '500':
          description: Internal error, or a Shopify write failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
components:
  schemas:
    BrandFeatureUpdateRequest:
      oneOf:
        - type: object
          properties:
            brand_feature_type:
              type: string
              enum:
                - content_block
            upsert_metaobjects:
              type: array
              items:
                $ref: '#/components/schemas/ProContentBlock'
              description: >-
                Metaobjects to create or update (matched by `handle`), all of
                `brand_feature_type`.
            delete_metaobjects_by_handle:
              type: array
              items:
                type: string
              description: Handles of this feature's metaobjects to delete.
          required:
            - brand_feature_type
            - upsert_metaobjects
            - delete_metaobjects_by_handle
        - type: object
          properties:
            brand_feature_type:
              type: string
              enum:
                - image_setting
            upsert_metaobjects:
              type: array
              items:
                $ref: '#/components/schemas/ProImageSetting'
              description: >-
                Metaobjects to create or update (matched by `handle`), all of
                `brand_feature_type`.
            delete_metaobjects_by_handle:
              type: array
              items:
                type: string
              description: Handles of this feature's metaobjects to delete.
          required:
            - brand_feature_type
            - upsert_metaobjects
            - delete_metaobjects_by_handle
        - type: object
          properties:
            brand_feature_type:
              type: string
              enum:
                - product_duplicate
            upsert_metaobjects:
              type: array
              items:
                $ref: '#/components/schemas/ProProductDuplicate'
              description: >-
                Metaobjects to create or update (matched by `handle`), all of
                `brand_feature_type`.
            delete_metaobjects_by_handle:
              type: array
              items:
                type: string
              description: Handles of this feature's metaobjects to delete.
          required:
            - brand_feature_type
            - upsert_metaobjects
            - delete_metaobjects_by_handle
        - type: object
          properties:
            brand_feature_type:
              type: string
              enum:
                - ab_test
            upsert_metaobjects:
              type: array
              items:
                $ref: '#/components/schemas/ProAbTest'
              description: >-
                Metaobjects to create or update (matched by `handle`), all of
                `brand_feature_type`.
            delete_metaobjects_by_handle:
              type: array
              items:
                type: string
              description: Handles of this feature's metaobjects to delete.
          required:
            - brand_feature_type
            - upsert_metaobjects
            - delete_metaobjects_by_handle
      discriminator:
        propertyName: brand_feature_type
    Detail:
      type: object
      properties:
        detail:
          type: string
      required:
        - detail
      description: 'Every 4xx/5xx body: `{detail}`.'
    ProContentBlock:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
        handle:
          type: string
          description: The metaobject handle; an existing handle is updated.
        index:
          type: integer
          description: Grid position the block is placed at.
        span_rows:
          type: integer
        aspect_ratio:
          type: number
        span_columns:
          type: integer
        visibility:
          type:
            - string
            - 'null'
          enum:
            - desktop
            - mobile
            - null
          description: Show on one breakpoint only; absent = both.
        content:
          anyOf:
            - $ref: '#/components/schemas/ProImageContent'
            - $ref: '#/components/schemas/ProVideoContent'
            - $ref: '#/components/schemas/ProSpaceContent'
            - $ref: '#/components/schemas/ProInstagramImageContent'
            - $ref: '#/components/schemas/ProInstagramVideoContent'
        hover_image:
          anyOf:
            - $ref: '#/components/schemas/ProImageContent'
            - $ref: '#/components/schemas/ProInstagramImageContent'
            - type: 'null'
        link:
          $ref: '#/components/schemas/ContentLink'
        text:
          $ref: '#/components/schemas/ProContentBlockText'
      required:
        - handle
        - index
        - span_rows
        - aspect_ratio
        - span_columns
        - content
    ProImageSetting:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
        handle:
          type: string
        product_gid:
          type: string
          description: Shopify GID.
        default_image_gid:
          type: string
          description: Shopify GID.
        hover_image_gid:
          type:
            - string
            - 'null'
      required:
        - handle
        - product_gid
        - default_image_gid
    ProProductDuplicate:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
        handle:
          type: string
        product_gid:
          type: string
          description: Shopify GID.
        default_image_gid:
          type: string
          description: Shopify GID.
        hover_image_gid:
          type:
            - string
            - 'null'
        index:
          type:
            - integer
            - 'null'
          description: Grid position of the duplicate.
        created_at:
          type:
            - integer
            - 'null'
      required:
        - handle
        - product_gid
        - default_image_gid
    ProAbTest:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
          description: >-
            The test's Shopify metaobject GID. Required unless
            generated_conclusion is set: a generation without it answers 500 and
            writes nothing.
        handle:
          type: string
        start_date:
          type: string
        end_date:
          type: string
        experiment_name:
          type: string
        notify_email:
          type: string
        generated_conclusion:
          type:
            - string
            - 'null'
          description: A stored conclusion; when non-empty it is returned as-is.
      required:
        - handle
        - start_date
        - end_date
        - experiment_name
        - notify_email
    ProImageContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - image
          default: image
        gid:
          type: string
          description: Shopify GID.
        filename:
          type: string
        alt_text:
          type:
            - string
            - 'null'
      required:
        - gid
        - filename
    ProVideoContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - video
          default: video
        gid:
          type: string
          description: Shopify GID.
        filename:
          type: string
      required:
        - gid
        - filename
    ProSpaceContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - space
          default: space
        height:
          type:
            - integer
            - 'null'
    ProInstagramImageContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - instagram_image
          default: instagram_image
        gid:
          type: string
          description: Shopify GID.
        creator:
          type: string
        post_url:
          type: string
        post_id:
          type: string
        media_id:
          type: string
        alt_text:
          type:
            - string
            - 'null'
      required:
        - gid
        - creator
        - post_url
        - post_id
        - media_id
    ProInstagramVideoContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - instagram_video
          default: instagram_video
        gid:
          type: string
          description: Shopify GID.
        creator:
          type: string
        post_url:
          type: string
        post_id:
          type: string
        media_id:
          type: string
      required:
        - gid
        - creator
        - post_url
        - post_id
        - media_id
    ContentLink:
      type:
        - object
        - 'null'
      properties:
        type:
          type: string
          enum:
            - collection
            - page
            - product
            - article
            - url
        gid:
          type: string
          description: Shopify GID.
        handle:
          type: string
        url:
          type:
            - string
            - 'null'
        article_handle:
          type:
            - string
            - 'null'
      required:
        - type
        - gid
        - handle
    ProContentBlockText:
      type:
        - object
        - 'null'
      properties:
        header:
          $ref: '#/components/schemas/ContentBlockTextProperties'
        body:
          $ref: '#/components/schemas/ContentBlockTextProperties'
        horizontal_alignment:
          type:
            - string
            - 'null'
          enum:
            - start
            - center
            - end
            - null
        vertical_alignment:
          type:
            - string
            - 'null'
          enum:
            - start
            - center
            - end
            - null
        background_overlay:
          type:
            - string
            - 'null'
        overlay_style:
          type:
            - string
            - 'null'
          enum:
            - solid
            - gradient
            - null
        text_shadow:
          type:
            - boolean
            - 'null'
        gap:
          type:
            - string
            - 'null'
    ContentBlockTextProperties:
      type:
        - object
        - 'null'
      properties:
        html_tag:
          type: string
        color_hex:
          type:
            - string
            - 'null'
        bold:
          type:
            - boolean
            - 'null'
        italic:
          type:
            - boolean
            - 'null'
        underline:
          type:
            - boolean
            - 'null'
        text:
          type:
            - string
            - 'null'
        translations:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
          description: Text per locale, keyed by locale code.
      required:
        - html_tag
  securitySchemes:
    ShopifySessionToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Shopify App Bridge session token of the embedded Depict: Search &
        Merchandising app. The shop in the token determines the merchant;
        merchant_id parameters must belong to that shop.

````