> ## 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 or update a collection version > Saves the body as a version of the collection without publishing it (publishing is PUT …/publish_version/{version}); `version` null or unknown creates a new version. Side effects: writes the version row, and when `is_market_active` is true deactivates the other versions of the same market or market group; then triggers a Shopify order sync-back (its failure does not fail the save). Setting `is_market_active` true makes the version live for its market, so it requires collection versions in the plan like publishing does (402 otherwise); drafting never does. Returns the version as stored. ## OpenAPI ````yaml /api-reference/openapi/lite.json put /collections/{collection_id}/update_version 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: /collections/{collection_id}/update_version: put: summary: Create or update a collection version description: >- Saves the body as a version of the collection without publishing it (publishing is PUT …/publish_version/{version}); `version` null or unknown creates a new version. Side effects: writes the version row, and when `is_market_active` is true deactivates the other versions of the same market or market group; then triggers a Shopify order sync-back (its failure does not fail the save). Setting `is_market_active` true makes the version live for its market, so it requires collection versions in the plan like publishing does (402 otherwise); drafting never does. Returns the version as stored. operationId: collectionVersionUpdate parameters: - schema: type: string description: Numeric Shopify collection id. required: true description: Numeric Shopify collection id. name: collection_id in: path - schema: type: string description: Lite merchant id, e.g. `shopify-`. required: true description: Lite merchant id, e.g. `shopify-`. name: merchant_id in: query requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LiteCollectionVersionUpdateInput' responses: '200': description: The saved version. content: application/json: schema: $ref: '#/components/schemas/LiteCollectionVersionDto' '400': description: >- The query or body failed the schema (including metafield_sort not matching sort_order), or an attachment id is unknown. content: application/json: schema: $ref: '#/components/schemas/Detail' '401': description: Not authenticated. content: application/json: schema: $ref: '#/components/schemas/Detail' '402': description: >- `is_market_active` true, but the plan does not include collection versions (Merchandising at Medium or above, or the free trial). content: application/json: schema: $ref: '#/components/schemas/Paywall' '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. 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. content: application/json: schema: $ref: '#/components/schemas/Detail' components: schemas: LiteCollectionVersionUpdateInput: type: object properties: sort_order: $ref: '#/components/schemas/LiteCollectionSortOrder' pinned_main_product_ids: type: array items: type: string description: Product ids pinned to the top, in order. collection_boost_rules: type: array items: $ref: '#/components/schemas/BoostBuryRule' use_collection_specific_boost_bury: type: boolean unpin_oos: type: boolean metafield_sort: anyOf: - $ref: '#/components/schemas/MetafieldSortConfig' - type: 'null' description: Required exactly when sort_order is METAFIELD_ASC/METAFIELD_DESC. active_attachment_ids: type: - array - 'null' items: type: string format: uuid description: Null/absent leaves the stored attachments unchanged. version_name: type: - string - 'null' version: type: - string - 'null' format: uuid description: The version to update; null creates a new version. market_id: type: - string - 'null' market_group_id: type: - string - 'null' is_market_active: type: - boolean - 'null' required: - sort_order - pinned_main_product_ids - collection_boost_rules - use_collection_specific_boost_bury - unpin_oos - version_name - version LiteCollectionVersionDto: type: object properties: collection_id: type: string description: Numeric Shopify collection id. version: type: string description: Version UUID. version_name: type: - string - 'null' sort_order: $ref: '#/components/schemas/LiteCollectionSortOrder' pinned_main_product_ids: type: array items: type: string collection_boost_rules: type: array items: $ref: '#/components/schemas/BoostBuryRule' use_collection_specific_boost_bury: type: boolean unpin_oos: type: boolean main: type: boolean description: This is the collection's published (main) version. updated_at: type: string description: Naive UTC. market_id: type: - string - 'null' description: Set when the version targets one Shopify market. market_group_id: type: - string - 'null' description: Set when the version targets a market group. is_market_active: type: boolean description: Published to its market / market group. scheduled_publish_at: type: - string - 'null' format: date-time description: >- UTC ISO timestamp (`Z`) the cron will publish it at; null when unscheduled. scheduled_by_email: type: - string - 'null' metafield_sort: anyOf: - $ref: '#/components/schemas/MetafieldSortConfig' - type: 'null' active_attachment_ids: type: array items: type: string required: - collection_id - version - version_name - sort_order - pinned_main_product_ids - collection_boost_rules - use_collection_specific_boost_bury - unpin_oos - main - updated_at - market_id - market_group_id - is_market_active - scheduled_publish_at - scheduled_by_email - metafield_sort - active_attachment_ids Detail: type: object properties: detail: type: string required: - detail description: 'Every 4xx/5xx body: `{detail}`.' Paywall: type: object properties: detail: type: string code: type: string enum: - product_required - collection_limit_exceeded - installation_frozen product: type: string enum: - search - recs - vm limit: type: integer required: - detail - code description: >- 402: the merchant's plan does not include this. Branch on `code`; show `detail`. LiteCollectionSortOrder: type: string enum: - ALPHA_ASC - ALPHA_DESC - BEST_SELLING - BEST_SELLING_BY_REVENUE - MOST_RELEVANT - TRENDING - TRENDING_BY_REVENUE - CREATED - CREATED_DESC - PRICE_ASC - PRICE_DESC - STOCK_DESC - CLICKS_DESC - METAFIELD_ASC - METAFIELD_DESC - MANUAL description: >- How Depict sorts the collection. MANUAL keeps the pinned order; METAFIELD_ASC/DESC sort by the version's `metafield_sort` key. BoostBuryRule: oneOf: - type: object properties: strength: type: integer description: >- Priority and direction: > 0 boosts matching products toward the top, < 0 buries them toward the bottom; a larger magnitude wins over a smaller one. top_n: type: - integer - 'null' description: >- Cap: only the first N matching products (best-ranked for a badge rule) are moved; null or absent = every match. type: type: string enum: - badge badge: $ref: '#/components/schemas/ProductBadgeType' required: - strength - type - badge - type: object properties: strength: type: integer description: >- Priority and direction: > 0 boosts matching products toward the top, < 0 buries them toward the bottom; a larger magnitude wins over a smaller one. top_n: type: - integer - 'null' description: >- Cap: only the first N matching products (best-ranked for a badge rule) are moved; null or absent = every match. type: type: string enum: - collection collection_id: type: string description: >- Numeric Shopify collection id (no gid:// prefix); matches that collection's products. required: - strength - type - collection_id - type: object properties: strength: type: integer description: >- Priority and direction: > 0 boosts matching products toward the top, < 0 buries them toward the bottom; a larger magnitude wins over a smaller one. top_n: type: - integer - 'null' description: >- Cap: only the first N matching products (best-ranked for a badge rule) are moved; null or absent = every match. type: type: string enum: - tag tags: type: array items: type: string description: >- Matches products carrying any of these Shopify tags (see GET /boost-bury/tags). required: - strength - type - tags - type: object properties: strength: type: integer description: >- Priority and direction: > 0 boosts matching products toward the top, < 0 buries them toward the bottom; a larger magnitude wins over a smaller one. top_n: type: - integer - 'null' description: >- Cap: only the first N matching products (best-ranked for a badge rule) are moved; null or absent = every match. type: type: string enum: - metafield key: type: string pattern: ^[A-Za-z0-9_-]{1,255}\.[A-Za-z0-9_-]{1,64}$ description: Product metafield as `namespace.key`. metafield_type: type: string enum: - number_integer - number_decimal - single_line_text_field - multi_line_text_field - url - color - date - date_time - boolean - rating - weight - dimension - volume description: >- The metafield's Shopify type; it decides which operators are allowed (measurement types allow only `exists`). operator: type: string enum: - exists - equals - gt - lt description: >- `exists` matches any product with the metafield set; `equals`/`gt`/`lt` compare against `value`. value: type: - string - 'null' description: The compared raw metafield value; null for `exists`. required: - strength - type - key - metafield_type - operator - value description: >- A merchant-wide rule that moves matching products up (boost) or down (bury) in every automatically sorted collection. `type` selects how products match. MetafieldSortConfig: type: object properties: key: type: string pattern: ^[A-Za-z0-9_-]{1,255}\.[A-Za-z0-9_-]{1,64}$ description: '`namespace.key`.' type: type: string enum: - number_integer - number_decimal - single_line_text_field - multi_line_text_field - url - color - date - date_time - boolean - rating - weight - dimension - volume required: - key - type ProductBadgeType: type: string enum: - on_sale - out_of_stock - new_in - bestseller - bestseller_revenue - slow_mover - few_variants_available - partially_out_of_stock - partially_low_stock - trending - trending_revenue - tag - collection description: Matches products currently carrying this badge. 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. ````