Asynchronously create a smart collection

POST 
/openapi/2026-01/collections/async

Initiates an asynchronous creation of a smart collection. Only smart collections are supported by this endpoint. Returns an async task ID immediately; use GetCollectionAsyncTask to poll the result.

Request

application/json

Body

Bodyrequired

collection objectrequired

Collection

titlestringrequired

The name of the collection

handlestring

A unique URL-friendly identifier for the collection

descriptionstring

The description of the collection

image object

Image

srcstringrequired

The source URL of the collection image

widthint32

The width of the collection image in pixels

heightint32

The height of the collection image in pixels

altstring

Alt text for the collection image

seo_titlestring

The SEO title for the collection

seo_keywordsstring[]

The keywords for SEO

seo_descriptionstring

The SEO description for the collection

sort_orderstring

Merchandise sorting rules. Options include: manual (default), sales-desc, price-asc, price-desc, views-desc, vendor-asc, vendor-desc, intelligent, and more

Default value: manual

product_idsstring[]

List of product IDs to include in the collection. Must be valid UUIDs

smartboolean

Whether it is a smart collection

match_rules object

Smart collection match rules

disjunctiveboolean

Logical relationship between rule modules:

• true: any rule module matched is sufficient (OR)
• false: all rule modules must be matched (AND, default)

rule_modules object[]

List of rule modules

Array [

disjunctiveboolean

Logical relationship between rules in this module:

• true: any rule matched is sufficient (OR)
• false: all rules must be matched (AND, default)

rules object[]

List of rules in this module

Array [

columnstring

Target field to apply the rule on. Supported values:

• title: product title
• product_status: product status
• tags: product tags
• vendor: vendor / supplier
• variant_price: SKU price
• variant_weight: SKU weight
• inventory_quantity: inventory quantity
• product_note: product note
• sales: sales volume
• real_sales: actual sales volume
• views: view count
• add_to_cart_count: add-to-cart count
• created_at: product creation time
• spu: SPU identifier
• spus_match: SPU match status
• published_at: publish time
• category_id: category ID
• brand: brand

relationstring

Comparison operator used for matching. Supported values:

• equals: equals
• not_equals: not equals
• starts_with: starts with
• ends_with: ends with
• contains: contains
• not_contains: does not contain
• greater_than: greater than
• less_than: less than
• top: top N results (usually used with sortable fields)

conditionstring

Condition value for the rule

• Text fields: plain string.
• Numeric fields: string convertible to a number.
• Time fields: timestamp or agreed time format.
• top relation: represents the value of N.

]

]

tagsstring[]

List of tags for the collection

Example

{
  "collection": {
    "title": "string",
    "handle": "string",
    "description": "string",
    "image": {
      "src": "string",
      "width": 0,
      "height": 0,
      "alt": "string"
    },
    "seo_title": "string",
    "seo_keywords": [
      "string"
    ],
    "seo_description": "string",
    "sort_order": "manual",
    "product_ids": [
      "string"
    ],
    "smart": true,
    "match_rules": {
      "disjunctive": true,
      "rule_modules": [
        {
          "disjunctive": true,
          "rules": [
            {
              "column": "string",
              "relation": "string",
              "condition": "string"
            }
          ]
        }
      ]
    },
    "tags": [
      "string"
    ]
  }
}

Responses

200

OK

application/json

Schema

Schema

codestring

error code

messagestring

error message

data object

async_task_idstring

Async task ID

error_messagestring

Error message returned when the task fails to be submitted. Empty if submission succeeded

collection object

Collection

idstring

Collection ID

titlestring

Title

descriptionstring

Description

handlestring

URL-friendly identifier (handle)

smartboolean

Smart

image object

Image

srcstring

The source URL of the image

widthint32

The width of the image in pixels

heightint32

The height of the image in pixels

altstring

Alt text for the image

seo_titlestring

SEO title

seo_keywordsstring[]

SEO keywords

seo_descriptionstring

SEO description

sort_orderstring

Sort order

created_atstring

Creation timestamp, in ISO-8601 format

updated_atstring

Last update timestamp, in ISO-8601 format

match_rules object

Smart collection match rules

disjunctiveboolean

Whether conditions are disjunctive (OR)

rule_modules object[]

List of rule modules

Array [

disjunctiveboolean

Whether conditions are disjunctive (OR)

rules object[]

List of rules in this module

Array [

columnstring

Column

relationstring

Relation

conditionstring

Condition

]

]

tagsstring[]

List of tags for the collection

product_countint64

Number of products in the collection

Example

{
  "code": "string",
  "message": "string",
  "data": {
    "async_task_id": "string",
    "error_message": "string",
    "collection": {
      "id": "string",
      "title": "string",
      "description": "string",
      "handle": "string",
      "smart": true,
      "image": {
        "src": "string",
        "width": 0,
        "height": 0,
        "alt": "string"
      },
      "seo_title": "string",
      "seo_keywords": [
        "string"
      ],
      "seo_description": "string",
      "sort_order": "string",
      "created_at": "string",
      "updated_at": "string",
      "match_rules": {
        "disjunctive": true,
        "rule_modules": [
          {
            "disjunctive": true,
            "rules": [
              {
                "column": "string",
                "relation": "string",
                "condition": "string"
              }
            ]
          }
        ]
      },
      "tags": [
        "string"
      ],
      "product_count": 0
    }
  }
}