> ## 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. # End, extend or refresh a collection version A/B test, or promote a winner > Applies one lifecycle action (see the body). Promoting makes the variant's version the collection's main version and syncs it to Shopify. Returns the updated test. ## OpenAPI ````yaml /api-reference/openapi/lite.json patch /collections/{collection_id}/ab-tests/{test_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: /collections/{collection_id}/ab-tests/{test_id}: patch: summary: >- End, extend or refresh a collection version A/B test, or promote a winner description: >- Applies one lifecycle action (see the body). Promoting makes the variant's version the collection's main version and syncs it to Shopify. Returns the updated test. operationId: collectionAbTestUpdate 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: The test's id. required: true description: The test's id. name: test_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/PatchCollectionVersionAbTestRequest' responses: '200': description: The updated test. content: application/json: schema: $ref: '#/components/schemas/CollectionVersionAbTest' '400': description: >- The query or body failed the schema, an `extend` date is out of bounds, 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 no such test on the collection. content: application/json: schema: $ref: '#/components/schemas/Detail' '409': description: >- The test's status does not allow this action (e.g. deleting a running test). 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: PatchCollectionVersionAbTestRequest: oneOf: - type: object properties: action: type: string enum: - end variant: type: - string - 'null' enum: - A - B - null required: - action - type: object properties: action: type: string enum: - promote variant: type: string enum: - A - B market_group_ids: type: array items: type: string minLength: 1 minItems: 1 maxItems: 50 description: >- The market groups the winner goes live in; `global` is the main version slot. A group the winning version does not belong to gets a copy of it, published there in place of that group's live version. Absent: the winner is published where it already belongs. required: - action - variant - type: object properties: action: type: string enum: - refresh_variant variant: type: string enum: - A - B required: - action - variant - type: object properties: action: type: string enum: - extend end_date: type: string format: date-time description: ISO 8601; without an offset it is read as UTC. required: - action - end_date description: >- `end` stops a running test; `promote` publishes the variant's version, in its own slot or in the given market groups, and ends the test; `refresh_variant` re-publishes a variant's ordering after its version changed; `extend` moves a running test's end later, at most 30 days after the start. CollectionVersionAbTest: type: object properties: test_id: type: string collection_id: type: string name: type: string variant_a_version_uuid: type: string variant_b_version_uuid: type: string scope_type: type: string enum: - all - market_groups market_group_ids: type: array items: type: string applies_to_market_ids: type: array items: type: string description: >- The scope as sorted numeric Shopify market ids; two running tests on a collection never share one. traffic_split: type: integer description: Percent of traffic routed to variant B (10–90). start_date: type: string format: date-time end_date: type: string format: date-time status: type: string enum: - running - ended - winner_promoted promoted_variant: type: - string - 'null' enum: - A - B - null promoted_market_group_ids: type: array items: type: string description: >- Market groups the winner was published in, `global` being the main slot. Empty when it went to its own slot only, or before this field existed. ended_at: type: - string - 'null' format: date-time description: >- When the test ended. Null while running, or if ended before this field existed. variant_a_settings: $ref: '#/components/schemas/CollectionVersionAbTestVariantSettings' variant_b_settings: $ref: '#/components/schemas/CollectionVersionAbTestVariantSettings' treatment: type: string enum: - order - full description: >- `order`: arms differ in product order only. `full`: also in content blocks, duplicates and image settings. created_at: type: string format: date-time created_by_email: type: string description: Always empty (the test is storefront-readable). required: - test_id - collection_id - name - variant_a_version_uuid - variant_b_version_uuid - scope_type - market_group_ids - applies_to_market_ids - traffic_split - start_date - end_date - status - promoted_variant - promoted_market_group_ids - ended_at - variant_a_settings - variant_b_settings - treatment - created_at - created_by_email Detail: type: object properties: detail: type: string required: - detail description: 'Every 4xx/5xx body: `{detail}`.' CollectionVersionAbTestVariantSettings: type: - object - 'null' properties: 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 first_product_ids: type: array items: type: string description: >- The first products of the variant's order when the test started, at most 24. required: - version_name - sort_order - pinned_main_product_ids - collection_boost_rules - use_collection_specific_boost_bury - unpin_oos - first_product_ids description: >- The variant's rules when the test started, so the results stay explained after the version is edited. Null on older tests. 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's unpinned products, within each boost/bury strength. BEST_SELLING: units sold in the last 30 days (_BY_REVENUE: revenue). TRENDING: units sold in the last 7 days (_BY_REVENUE: revenue). Unit ties on either break by 30-day revenue. CLICKS_DESC: clicks in the last 30 days. STOCK_DESC: total stock. CREATED: oldest first, CREATED_DESC: newest first, by the store's New in date (published or created, per dynamic status). PRICE_*, ALPHA_*: price, title. METAFIELD_ASC/DESC: the version's `metafield_sort` key. MANUAL: the saved order, never re-sorted, and boost/bury does not apply. MOST_RELEVANT: not a Depict sort. It comes from Shopify's relevance sort, which Depict cannot compute: Depict keeps the collection's existing order in Shopify and still applies boost/bury. After Depict's first write that existing order is the one Depict last wrote, so it stops following Shopify's relevance and earlier boosts and pins linger in it. 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. 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.