Create a smart collection

Requires write_products access scope.
For more info, refer to:
access permission.
POST https://{handle}.myshopline.com/admin/openapi/v20270301/products/smart_collections.json
handle : The store's unique identifier, which is the prefix of the store's domain name. For example, if a store's domain name is open001.myshopline.com , the store handle is open001 .
Create a new smart collection in the store.
Request Headers
  • Content-Type string required
    The field must be set to the fixed value application/json; charset=utf-8.
  • Authorization string required
    The access token for the API resource. Refer to App authorization to obtain the access token, and then pass the obtained token in the Bearer format.
    Example:
    Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA
Request Body
  • smart_collectionobject required
    Smart collection information.
  • bannerobject
    The cover image of the collection.
  • alt string
    The alternative textual description of the collection banner, usually a word or phrase with the characteristics or content of the image.
    Maximum length: 512
    Example: This is an image alt
  • id string
    The unique ID of an existing image. Omit this field if you add new image via src.
    Maximum length: 64
    Example: 5759070976424132652
  • src string
    The link to the image, represented as a URL.
    Maximum length: 255
    Example: https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png
  • body_html string
    The collection description.
    Maximum size: 64 KB
    Example: This is a description
  • disjunctive boolean
    Used to define the logical relationship of product filtering criteria in the smart collection.
    • true: A product only needs to meet any one of the filtering criteria to be included in the smart collection.
    • false: A product must meet all of the filtering criteria to be included in the smart collection.
    Default value: true
  • handle string
    The semantically unique identifier for the collection, which is generated based on title by default.
    Maximum length: 255
    Example: collection-handle
  • imageobject
    The image of the collection.
  • alt string
    The alternative textual description of the collection image, usually a word or phrase with the characteristics or content of the image.
    Maximum length: 512
    Example: This is an image alt
  • id string
    The unique ID of an existing image. Omit this field if you add new image via src.
    Maximum length: 64
    Example: 5759070976424132652
  • src string
    The link to the collection image, represented as a URL.
    Maximum length: 255
    Example: https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png
  • path string
    The relative path of the collection page.
    Maximum length: 512
    Example: /collections/spring
  • published_scope string
    The published scope of collection sales channels. The value of this field is fixed to web, indicating an online store.
  • rulesobject[] required
    Rules for filtering products in the smart collection.
  • column string required
    The field used for filtering.
    • title: Product title
    • sale_price: Product variant selling price
    • compared_at_price: Product variant original price
    • tag: Product tag
    • inventory: Product inventory
    • vendor: Brand or manufacturer
    • variant_weight: Product variant weight
    • variant_title: Product variant title
    • created_at: Product creation time
    • sales_last_3_days: Product sales volume in the last 3 days
    • sales_last_7_days: Product sales volume in the last 7 days
    • sales_last_15_days: Product sales volume in the last 15 days
    • sales_last_30_days: Product sales volume in the last 30 days
    • sales_last_60_days: Product sales volume in the last 60 days
    • sales: Product sales volume in the last 90 days
    • view: Product page views
    • add_to_cart: Product add-to-cart quantity
    • type: Custom product type
    • product_taxonomy_node_id: Standard product type
    • product_taxonomy_node_id_with_descendants：Standard product type with subcategories
    • product_metafield_definition: Value of product metafield
    Example: title
  • condition string
    The value to be matched, such as T shirt for the tag or 10.00 for the price.
    When relation is is_not_set or is_set, the field is invalid.
    Example: true
  • condition_object_id long
    The ID of the metafield object.
    Example: 483749284
  • relation string required
    The relationship between the field and the value.
    • equals: Indicates equal to
    • not_equals: Indicates not equal to
    • starts_with: Indicates prefix matching
    • ends_with: Indicates suffix matching
    • contains: Indicates inclusion relationship
    • not_contains: Indicates non-inclusion relationship
    • greater_than: Indicates greater than
    • less_than: Indicates less than
    • is_not_set：Indicates all values are empty
    • is_set：Indicates values are not empty
    Example: equals
  • sort_order string
    Indicates the sorting method of the default sort value for the product list on the collection page.
    • alpha-asc: Sort by product name from A to Z
    • alpha-desc: Sort by product name from Z to A
    • updated-desc: Sort by update time from newest to oldest
    • updated-asc: Sort by update time from oldest to newest
    • manual: Sort by custom order
    • created-desc: Sort by creation time from newest to oldest
    • created-asc: Sort by creation time from oldest to newest
    • price-asc: Sort by the lowest selling price of product variants in ascending order
    • price-desc: Sort by the lowest selling price of product variants in descending order
    • best-selling-last3days: Sort by sales volume in the last 3 days in descending order
    • best-selling-last7days: Sort by sales volume in the last 7 days in descending order
    • best-selling-last15days: Sort by sales volume in the last 15 days in descending order
    • best-selling-last30days: Sort by sales volume in the last 30 days in descending order
    • best-selling-last60days: Sort by sales volume in the last 60 days in descending order
    • best-selling: Sort by sales volume in the last 90 days in descending order
    • additional-purchase-rate-last3days: Sort by add-to-cart rate in the last 3 days in descending order
    • additional-purchase-rate-last7days: Sort by add-to-cart rate in the last 7 days in descending order
    • additional-purchase-rate-last15days: Sort by add-to-cart rate in the last 15 days in descending order
    • additional-purchase-rate-last30days: Sort by add-to-cart rate in the last 30 days in descending order
    • additional-purchase-rate-last60days: Sort by add-to-cart rate in the last 60 days in descending order
    • additional-purchase-rate-last90days: Sort by add-to-cart rate in the last 90 days in descending order
    • conversion-rate-last3days: Sort by conversion rate in the last 3 days in descending order
    • conversion-rate-last7days: Sort by conversion rate in the last 7 days in descending order
    • conversion-rate-last15days: Sort by conversion rate in the last 15 days in descending order
    • conversion-rate-desc: Sort by conversion rate in the last 30 days in descending order
    • conversion-rate-last60days: Sort by conversion rate in the last 60 days in descending order
    • conversion-rate-last90days: Sort by conversion rate in the last 90 days in descending order
    • additional-purchases-num-last3days: Sort by add-to-cart quantity in the last 3 days in descending order
    • additional-purchases-num-last7days: Sort by add-to-cart quantity in the last 7 days in descending order
    • additional-purchases-num-last15days: Sort by add-to-cart quantity in the last 15 days in descending order
    • additional-purchases-num-last30days: Sort by add-to-cart quantity in the last 30 days in descending order
    • additional-purchases-num-last60days: Sort by add-to-cart quantity in the last 60 days in descending order
    • add-to-cart-desc: Sort by add-to-cart quantity in the last 90 days in descending order
    • views-pv-last3days: Sort by page views in the last 3 days in descending order
    • views-pv-last7days: Sort by page views in the last 7 days in descending order
    • views-pv-last15days: Sort by page views in the last 15 days in descending order
    • views-pv-last30days: Sort by page views in the last 30 days in descending order
    • views-pv-last60days: Sort by page views in the last 60 days in descending order
    • view-desc: Sort by page views in the last 90 days in descending order
  • template_path string
    The theme template of the collection.
    Example: templates/collection.collection_template_name.json
  • title string required
    The title of the collection.
    Maximum length: 255
    Example: This is a collection title
Status Codes
For the complete list of codes and messages, see Http status code.
Response Headers
  • traceId
    A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise.
Response Body
  • smart_collectionobject
    Smart collection information.
  • bannerobject
    The cover image of the collection.
  • alt string
    The alternative textual description of the image, usually a word or phrase with the characteristics or content of the image.
    Example: This is an image alt
  • id string
    The unique identifier for the image.
    Example: 5785060242207917075
  • src string
    The link to the image, represented as a URL.
    Example: https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png
  • body_html string
    The collection description.
    Example: This is a description
  • created_at string
    The date and time when the collection was created. Format: ISO 8601.
    Example: 2021-09-03T14:11:54+00:00
  • disjunctive boolean
    Used to define the logical relationship of product filtering criteria in the smart collection.
    • true: A product only needs to meet any one of the filtering criteria to be included in the smart collection.
    • false: A product must meet all of the filtering criteria to be included in the smart collection.
  • handle string
    The semantically unique identifier for the collection, which is generated based on title by default.
    Example: collection-handle
  • id string
    The unique identifier for the collection.
    Example: 12257170618007271602093384
  • imageobject
    The collection image.
  • alt string
    The alternative textual description of the image, usually a word or phrase with the characteristics or content of the image.
    Example: This is an image alt
  • id string
    The unique identifier for the image.
    Example: 5785060242207917075
  • src string
    The link to the image, represented as a URL.
    Example: https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png
  • published_at string
    The date and time when the collection was published to the online store. Format: ISO 8601.
    Example: 2021-09-03T14:11:54+00:00
  • published_scope string
    The published scope of collection sales channels. The value of this field is fixed to web, indicating an online store.
  • rulesobject[]
    Rules for filtering products in the smart collection.
  • column string
    The field used for filtering.
    • title: Product title
    • sale_price: Product variant selling price
    • compared_at_price: Product variant original price
    • tag: Product tag
    • inventory: Product inventory
    • vendor: Brand or manufacturer
    • variant_weight: Product variant weight
    • variant_title: Product variant title
    • created_at: Product creation time
    • sales_last_3_days: Product sales volume in the last 3 days
    • sales_last_7_days: Product sales volume in the last 7 days
    • sales_last_15_days: Product sales volume in the last 15 days
    • sales_last_30_days: Product sales volume in the last 30 days
    • sales_last_60_days: Product sales volume in the last 60 days
    • sales: Product sales volume in the last 90 days
    • view: Product page views
    • add_to_cart: Product add-to-cart quantity
    • type: Custom product type
    • product_taxonomy_node_id: Standard product type
    • product_taxonomy_node_id_with_descendants：Standard product type with subcategories
    • product_metafield_definition: Value of product metafield
  • condition string
    The value to be matched, such as T shirt for tags or 10.00 for price.
    When relation is is_not_set or is_set, the field is invalid.
    Example: true
  • condition_object_id long
    The ID of the metafield object.
    Example: 483749284
  • relation string
    The relationship between the field and the value.
    • equals: Indicates equal to
    • not_equals: Indicates not equal to
    • starts_with: Indicates prefix matching
    • ends_with: Indicates suffix matching
    • contains: Indicates inclusion relationship
    • not_contains: Indicates non-inclusion relationship
    • greater_than: Indicates greater than
    • less_than: Indicates less than
    • is_not_set：Indicates all values are empty
    • is_set：Indicates values are not empty
  • sort_order string
    Indicates the sorting method of the default sort value for the product list on the collection page.
    • alpha-asc: Sort by product name from A to Z
    • alpha-desc: Sort by product name from Z to A
    • updated-desc: Sort by update time from newest to oldest
    • updated-asc: Sort by update time from oldest to newest
    • manual: Sort by custom order
    • created-desc: Sort by creation time from newest to oldest
    • created-asc: Sort by creation time from oldest to newest
    • price-asc: Sort by the lowest selling price of product variants in ascending order
    • price-desc: Sort by the lowest selling price of product variants in descending order
    • best-selling-last3days: Sort by sales volume in the last 3 days in descending order
    • best-selling-last7days: Sort by sales volume in the last 7 days in descending order
    • best-selling-last15days: Sort by sales volume in the last 15 days in descending order
    • best-selling-last30days: Sort by sales volume in the last 30 days in descending order
    • best-selling-last60days: Sort by sales volume in the last 60 days in descending order
    • best-selling: Sort by sales volume in the last 90 days in descending order
    • additional-purchase-rate-last3days: Sort by add-to-cart rate in the last 3 days in descending order
    • additional-purchase-rate-last7days: Sort by add-to-cart rate in the last 7 days in descending order
    • additional-purchase-rate-last15days: Sort by add-to-cart rate in the last 15 days in descending order
    • additional-purchase-rate-last30days: Sort by add-to-cart rate in the last 30 days in descending order
    • additional-purchase-rate-last60days: Sort by add-to-cart rate in the last 60 days in descending order
    • additional-purchase-rate-last90days: Sort by add-to-cart rate in the last 90 days in descending order
    • conversion-rate-last3days: Sort by conversion rate in the last 3 days in descending order
    • conversion-rate-last7days: Sort by conversion rate in the last 7 days in descending order
    • conversion-rate-last15days: Sort by conversion rate in the last 15 days in descending order
    • conversion-rate-desc: Sort by conversion rate in the last 30 days in descending order
    • conversion-rate-last60days: Sort by conversion rate in the last 60 days in descending order
    • conversion-rate-last90days: Sort by conversion rate in the last 90 days in descending order
    • additional-purchases-num-last3days: Sort by add-to-cart quantity in the last 3 days in descending order
    • additional-purchases-num-last7days: Sort by add-to-cart quantity in the last 7 days in descending order
    • additional-purchases-num-last15days: Sort by add-to-cart quantity in the last 15 days in descending order
    • additional-purchases-num-last30days: Sort by add-to-cart quantity in the last 30 days in descending order
    • additional-purchases-num-last60days: Sort by add-to-cart quantity in the last 60 days in descending order
    • add-to-cart-desc: Sort by add-to-cart quantity in the last 90 days in descending order
    • views-pv-last3days: Sort by page views in the last 3 days in descending order
    • views-pv-last7days: Sort by page views in the last 7 days in descending order
    • views-pv-last15days: Sort by page views in the last 15 days in descending order
    • views-pv-last30days: Sort by page views in the last 30 days in descending order
    • views-pv-last60days: Sort by page views in the last 60 days in descending order
    • view-desc: Sort by page views in the last 90 days in descending order
  • template_path string
    The theme template of the collection.
    Example: templates/collection.collection_template_name.json
  • title string
    The title of the collection.
    Example: This is a title
  • updated_at string
    The date and time when the collection was last updated. Format: ISO 8601.
    Example: 2021-09-03T14:11:54+00:00
API Explorer
https://openapiceshidianpu.myshopline.com/admin/openapi/v20270301

ParamOptions

— header required

Body

required
{
  "smart_collection": {
    "banner": {
      "alt": "This is an image alt",
      "id": "5759070976424132652",
      "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
    },
    "body_html": "This is a description",
    "disjunctive": null,
    "handle": "collection-handle",
    "image": {
      "alt": "This is an image alt",
      "id": "5759070976424132652",
      "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
    },
    "path": "/collections/spring",
    "published_scope": null,
    "rules": [
      {}
    ],
    "sort_order": null,
    "template_path": "templates/collection.collection_template_name.json",
    "title": "This is a collection title"
  }
}

Language

curl --request POST \
     --url https://openapiceshidianpu.myshopline.com/admin/openapi/v20270301/products/smart_collections.json \
     --header 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA' \
     --header 'Content-Type: application/json; charset=utf-8' \
     --header 'accept: application/json'
Examples
Create a smart collection
Request
{
  "smart_collection": {
    "banner": {
      "alt": "This is an image alt",
      "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
    },
    "body_html": "This is a description",
    "disjunctive": true,
    "handle": "spring-clothing",
    "image": {
      "alt": "This is an image alt",
      "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
    },
    "path": "/collections/spring",
    "published_scope": "web",
    "rules": [
      {
        "column": "tag",
        "condition": "tag1",
        "relation": "equals"
      }
    ],
    "sort_order": "updated-asc",
    "title": "spring clothing"
  }
}
Response
{
  "smart_collection": {
    "banner": {
      "alt": "This is an image alt",
      "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png?type=banner"
    },
    "body_html": "This is a description",
    "created_at": "2026-01-21T11:37:42+08:00",
    "disjunctive": true,
    "handle": "spring-clothing-3",
    "id": "12273591337512073128362340",
    "image": {
      "alt": "This is an image alt",
      "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png?type=cover"
    },
    "published_at": "2026-01-21T11:37:42+08:00",
    "published_scope": "web",
    "rules": [
      {
        "column": "tag",
        "condition": "tag1",
        "condition_object_id": null,
        "relation": "equals"
      }
    ],
    "sort_order": "updated-asc",
    "template_path": null,
    "title": "spring clothing",
    "updated_at": "2026-01-21T11:37:42+08:00"
  }
}
Was this article helpful to you?
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
Legal
Privacy
Terms
Developer Agreement
LinkedInEmail
LinkedInEmail
© Copyright 2013-2026 SHOPLINE Limited.