> ## 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. # Preview a collection's products under a sort > Returns the collection's products ordered as `sort_order` (and the given version's pins and rules) would order them on the storefront. The body previews unsaved rules, pins, groupings or a metafield sort; send `{}` (or null fields) to use the saved ones. Read-only despite POST. ## OpenAPI ````yaml /api-reference/openapi/lite.json post /collections/{collection_id}/products 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}/products: post: summary: Preview a collection's products under a sort description: >- Returns the collection's products ordered as `sort_order` (and the given version's pins and rules) would order them on the storefront. The body previews unsaved rules, pins, groupings or a metafield sort; send `{}` (or null fields) to use the saved ones. Read-only despite POST. operationId: collectionGridProducts 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 - schema: $ref: '#/components/schemas/LiteCollectionSortOrder' required: true description: >- How Depict sorts the collection. MANUAL keeps the pinned order; METAFIELD_ASC/DESC sort by the version's `metafield_sort` key. name: sort_order in: query - schema: type: - string - 'null' description: The version whose saved settings apply; absent = main. required: false description: The version whose saved settings apply; absent = main. name: version in: query requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/CollectionProductsBody' - type: 'null' responses: '200': description: The products in grid order. content: application/json: schema: type: array items: $ref: '#/components/schemas/LiteCollectionProduct' '400': description: >- The query, path or body failed the schema; `detail` carries zod's messages. 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. 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: 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. CollectionProductsBody: type: object properties: boost_bury_rules: type: - array - 'null' items: $ref: '#/components/schemas/BoostBuryRule' description: Unsaved collection rules to preview; null = the saved ones. pinned_main_product_ids: type: - array - 'null' items: type: string description: Unsaved pins to preview; null = the saved ones. active_attachment_ids: type: - array - 'null' items: type: string description: Unsaved groupings to preview; null = the saved ones. metafield_sort: anyOf: - $ref: '#/components/schemas/MetafieldSortConfig' - type: 'null' LiteCollectionProduct: type: object properties: main_product_id: type: string description: Shopify product id (numeric string). title: type: string handle: type: string images: type: array items: $ref: '#/components/schemas/ShopifyImage' tags: type: array items: type: string price: type: - number - 'null' status: $ref: '#/components/schemas/ProductStatus' has_online_store_channel: type: - boolean - 'null' description: >- Whether the Online Store sales channel is enabled; null when ingestion has not stamped it. in_stock: type: boolean quantity: type: integer description: Summed available quantity over variants. badges: type: array items: anyOf: - type: object properties: type: type: string enum: - on_sale sale_percentage: type: number markets_on_sale: type: - array - 'null' items: type: object properties: market_id: type: string display_name: type: string required: - market_id - display_name description: Markets where the product is on sale, when not all are. total_markets: type: - integer - 'null' market_group_display_name: type: - string - 'null' required: - type - sale_percentage - type: object properties: type: type: string enum: - out_of_stock required: - type - type: object properties: type: type: string enum: - partially_out_of_stock required: - type - type: object properties: type: type: string enum: - partially_low_stock required: - type - type: object properties: type: type: string enum: - new_in published_at: type: string date_source: type: string enum: - published_at - created_at required: - type - published_at - type: object properties: value: type: number n_days: type: integer description: Window the value was measured over. type: type: string enum: - bestseller required: - value - n_days - type - type: object properties: value: type: number n_days: type: integer description: Window the value was measured over. type: type: string enum: - bestseller_revenue currency: type: - string - 'null' description: ISO currency of `value`. required: - value - n_days - type - type: object properties: value: type: number n_days: type: integer description: Window the value was measured over. type: type: string enum: - slow_mover required: - value - n_days - type - type: object properties: value: type: number n_days: type: integer description: Window the value was measured over. type: type: string enum: - trending required: - value - n_days - type - type: object properties: value: type: number n_days: type: integer description: Window the value was measured over. type: type: string enum: - trending_revenue currency: type: - string - 'null' description: ISO currency of `value`. required: - value - n_days - type - type: object properties: type: type: string enum: - few_variants_available variant_options_available: type: array items: type: object additionalProperties: type: string description: >- Option name → value, one entry per variant still available. n_variants_total: type: integer required: - type - variant_options_available - n_variants_total - type: object properties: type: type: string enum: - tag tag: type: string required: - type - tag - type: object properties: type: type: string enum: - collection collection_id: type: string collection_title: type: string required: - type - collection_id - collection_title - $ref: '#/components/schemas/MetafieldProductBadge' skus: type: array items: type: string created_at: type: string published_at: type: - string - 'null' variants: type: array items: $ref: '#/components/schemas/LiteVariant' sort_index: type: integer description: Position in the collection's sort, ignoring pins. applied_boost_bury_rule: 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 - type: 'null' description: The rule that moved this product, if any. market_quantities: type: - object - 'null' additionalProperties: type: number description: Available quantity per market id. variant_ids_in_collection: type: - array - 'null' items: type: string variants_in_collection: type: - integer - 'null' variants_total: type: - integer - 'null' metafield_sort_value: type: - string - 'null' description: The sort metafield's value under a METAFIELD_* sort. required: - main_product_id - title - handle - images - tags - price - status - has_online_store_channel - in_stock - quantity - badges - skus - created_at - published_at - variants - sort_index - market_quantities - variant_ids_in_collection - variants_in_collection - variants_total Detail: type: object properties: detail: type: string required: - detail description: 'Every 4xx/5xx body: `{detail}`.' 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 ShopifyImage: type: object properties: id: type: string url: type: string width: type: - integer - 'null' height: type: - integer - 'null' alt: type: - string - 'null' required: - id - url ProductStatus: type: string enum: - ACTIVE - ARCHIVED - DRAFT - SCHEDULED - UNLISTED MetafieldProductBadge: type: object properties: type: type: string enum: - metafield key: type: string description: The metafield, `namespace.key`. value: type: string required: - type - key - value LiteVariant: type: object properties: id: type: string title: type: string sku: type: - string - 'null' quantity_available: type: integer image_url: type: - string - 'null' selected_options: type: array items: type: object properties: name: type: string value: type: string required: - name - value required: - id - title - sku - quantity_available - image_url - selected_options 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. ````