The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Anchor to section titled 'undefined'

SmartCollection

Requires products access scope.

A smart collection is a grouping of products defined by rules that are set by the merchant. Shopify automatically changes the contents of a smart collection based on the rules. Smart collections, like other types of collections, are used to break down the catalog of products into categories and make the shop easier to browse.

By default, a store can have up to 5000 smart collections.

The Collect resource is used to connect a product to a smart collection. However, these collects can't be added or removed from the API as they're managed by the rules of the smart collection.

You can use the CustomCollection resource to work with collections where each product in the collection is manually chosen by the merchant.

Was this section helpful?
#Endpoints
Anchor to section titled 'The SmartCollection resource'

The SmartCollection resource

Properties
body_html
->descriptionHtml
The description of the smart collection. Includes HTML markup. Many shop themes display this on the smart collection page.
handle
->handle
A human-friendly unique string for the smart collection. Automatically generated from the title. Used in shop themes by the Liquid templating language to refer to the smart collection. (maximum: 255 characters)
id
->id
The ID of the smart collection.
image
->image

The image associated with the smart collection. Valid values:

published_at
->publishDate
The date and time (ISO 8601 format) that the smart collection was published. Returns null when the collection is hidden.
published_scope
->publishable
Whether the smart collection is published to the Point of Sale channel. Valid values:
rules
->ruleSet

The list of rules that define what products go into the smart collection. Each rule has the following properties:

disjunctive
->appliedDisjunctively
Whether the product must match all the rules to be included in the smart collection. Valid values:
sort_order
->sortOrder

The order of the products in the smart collection. Valid values:

template_suffix
->templateSuffix
The suffix of the Liquid template that the shop uses. By default, the original template is called product.liquid, and additional templates are called product.suffix.liquid.
title
->title
The name of the smart collection. Maximum length: 255 characters.
updated_at
read-only
->updatedAt
The date and time (ISO 8601 format) when the smart collection was last modified.
Was this section helpful?
{}The SmartCollection resource
{
  "body_html": "<p>The best selling ipod ever</p>",
  "handle": "smart-ipods",
  "id": 482865238,
  "image": {
    "src": "http://static.shopify.com/collections/ipod.jpg?0",
    "alt": "iPods"
  },
  "published_at": "2008-02-01T19:00:00-05:00",
  "published_scope": "global",
  "rules": {
    "column": "variant_price",
    "relation": "less_than",
    "condition": "20"
  },
  "disjunctive": false,
  "sort_order": "alpha-asc",
  "template_suffix": null,
  "title": "Smart iPods",
  "updated_at": "2008-02-01T19:00:00-05:00"
}
Anchor to section titled 'POST request, Creates a smart collection'

post
Creates a smart collection

collectionCreate
Creates a new smart collection using the specified rules.
Anchor to section titled 'Parameters of Creates a smart collection'

Parameters

api_version
string
required
Was this section helpful?
Anchor to section titled 'Examples of Creates a smart collection'

Examples

Request body
smartcollection
Smart_collection resource
Was this section helpful?
post
/admin/api/2024-10/smart_collections.json
Copy
curl -d '{"smart_collection":{"title":"Macbooks","rules":[{"column":"vendor","relation":"equals","condition":"Apple"}],"image":{"attachment":"R0lGODlhAQABAIAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==\n","alt":"iPod"}}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2024-10/smart_collections.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 201 Created
{
  "smart_collection": {
    "id": 1063001326,
    "handle": "macbooks",
    "title": "Macbooks",
    "updated_at": "2024-09-27T06:59:05-04:00",
    "body_html": null,
    "published_at": "2024-09-27T06:59:05-04:00",
    "sort_order": "best-selling",
    "template_suffix": null,
    "disjunctive": false,
    "rules": [
      {
        "column": "vendor",
        "relation": "equals",
        "condition": "Apple"
      }
    ],
    "published_scope": "web",
    "admin_graphql_api_id": "gid://shopify/Collection/1063001326",
    "image": {
      "created_at": "2024-09-27T06:59:05-04:00",
      "alt": "iPod",
      "width": 1,
      "height": 1,
      "src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/collections/df3e567d6f16d040326c7a0ea29a4f41.gif?v=1727434745"
    }
  }
}
Anchor to section titled 'GET request, Retrieves a list of smart collections'

get
Retrieves a list of smart collections

collections
Retrieves a list of smart collections. Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.
Anchor to section titled 'Parameters of Retrieves a list of smart collections'

Parameters

api_version
string
required
fields
Show only certain fields, specified by a comma-separated list of field names.
handle
Filter results by smart collection handle.
ids
Show only the smart collections specified by a comma-separated list of IDs.
limit
≤ 250
default 50
The number of results to show.
product_id
Show smart collections that includes the specified product.
published_at_max
Show smart collections published before this date. (format: 2014-04-25T16:15:47-04:00)
published_at_min
Show smart collections published after this date. (format: 2014-04-25T16:15:47-04:00)
published_status
default any
Filter results based on the published status of smart collections.
since_id
Restrict results to after the specified ID.
title
Show smart collections with the specified title.
updated_at_max
Show smart collections last updated before this date. (format: 2014-04-25T16:15:47-04:00)
updated_at_min
Show smart collections last updated after this date. (format: 2014-04-25T16:15:47-04:00)
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a list of smart collections'

Examples

Query parameters
sinceid=482865238
Restrict results to after the specified ID.
Was this section helpful?
get
/admin/api/2024-10/smart_collections.json?sinceid=482865238
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/smart_collections.json?since_id=482865238" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "smart_collections": [
    {
      "id": 1063001316,
      "handle": "ipods-1",
      "title": "IPods",
      "updated_at": "2024-09-27T06:58:46-04:00",
      "body_html": null,
      "published_at": "2024-09-27T06:58:46-04:00",
      "sort_order": "best-selling",
      "template_suffix": null,
      "disjunctive": false,
      "rules": [
        {
          "column": "title",
          "relation": "starts_with",
          "condition": "iPod"
        }
      ],
      "published_scope": "web",
      "admin_graphql_api_id": "gid://shopify/Collection/1063001316"
    }
  ]
}
Anchor to section titled 'GET request, Retrieves a single smart collection'

get
Retrieves a single smart collection

collection
Retrieves a single smart collection
Anchor to section titled 'Parameters of Retrieves a single smart collection'

Parameters

api_version
string
required
smart_collection_id
string
required
fields
Show only certain fields, specified by a comma-separated list of field names.
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a single smart collection'

Examples

Path parameters
smartcollectionid=482865238
string
required
Was this section helpful?
get
/admin/api/2024-10/smart_collections/482865238.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/smart_collections/482865238.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "smart_collection": {
    "id": 482865238,
    "handle": "smart-ipods",
    "title": "Smart iPods",
    "updated_at": "2008-02-01T19:00:00-05:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "published_at": "2008-02-01T19:00:00-05:00",
    "sort_order": "manual",
    "template_suffix": null,
    "products_count": 2,
    "disjunctive": false,
    "rules": [
      {
        "column": "type",
        "relation": "equals",
        "condition": "Cult Products"
      }
    ],
    "published_scope": "web",
    "admin_graphql_api_id": "gid://shopify/Collection/482865238",
    "image": {
      "created_at": "2024-09-27T06:46:59-04:00",
      "alt": "MP3 Player 8gb",
      "width": 123,
      "height": 456,
      "src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/collections/ipod_nano_8gb.jpg?v=1727434019"
    }
  }
}
Anchor to section titled 'GET request, Retrieves a count of smart collections'

get
Retrieves a count of smart collections

collectionsCount
Retrieves a count of smart collections
Anchor to section titled 'Parameters of Retrieves a count of smart collections'

Parameters

api_version
string
required
product_id
Show smart collections that include the specified product.
published_at_max
Show smart collections published before this date. (format: 2014-04-25T16:15:47-04:00)
published_at_min
Show smart collections published after this date. (format: 2014-04-25T16:15:47-04:00)
published_status
default any
Filter results based on the published status of smart collections.
title
Show smart collections with the specified title.
updated_at_max
Show smart collections last updated before this date. (format: 2014-04-25T16:15:47-04:00)
updated_at_min
Show smart collections last updated after this date. (format: 2014-04-25T16:15:47-04:00)
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a count of smart collections'

Examples

Was this section helpful?
get
/admin/api/2024-10/smart_collections/count.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/smart_collections/count.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "count": 1
}
Anchor to section titled 'PUT request, Updates an existing smart collection'

put
Updates an existing smart collection

collectionUpdate
Updates an existing smart collection
Anchor to section titled 'Parameters of Updates an existing smart collection'

Parameters

api_version
string
required
smart_collection_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Updates an existing smart collection'

Examples

Path parameters
smartcollectionid=482865238
string
required
Request body
smartcollection
Smart_collection resource
Was this section helpful?
put
/admin/api/2024-10/smart_collections/482865238.json
Copy
curl -d '{"smart_collection":{"id":482865238,"published":false}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2024-10/smart_collections/482865238.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 200 OK
{
  "smart_collection": {
    "title": "Smart iPods",
    "handle": "smart-ipods",
    "body_html": "<p>The best selling ipod ever</p>",
    "id": 482865238,
    "published_at": null,
    "updated_at": "2024-09-27T06:58:59-04:00",
    "sort_order": "manual",
    "template_suffix": null,
    "disjunctive": false,
    "rules": [
      {
        "column": "type",
        "relation": "equals",
        "condition": "Cult Products"
      }
    ],
    "published_scope": "web",
    "admin_graphql_api_id": "gid://shopify/Collection/482865238",
    "image": {
      "created_at": "2024-09-27T06:46:59-04:00",
      "alt": "MP3 Player 8gb",
      "width": 123,
      "height": 456,
      "src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/collections/ipod_nano_8gb.jpg?v=1727434019"
    }
  }
}
Anchor to section titled 'PUT request, Updates the ordering type of products in a smart collection'

put
Updates the ordering type of products in a smart collection

collectionUpdate
collectionReorderProducts
Updates the ordering type of products in a smart collection
Anchor to section titled 'Parameters of Updates the ordering type of products in a smart collection'

Parameters

api_version
string
required
smart_collection_id
string
required
products
An array of product IDs, in the order that you want them to appear at the top of the collection. When products is specified but empty, any previously sorted products are cleared.
sort_order
default (current value)
The type of sorting to apply. Valid values are listed in the Properties section above.
Was this section helpful?
Anchor to section titled 'Examples of Updates the ordering type of products in a smart collection'

Examples

Query parameters
Was this section helpful?
put
/admin/api/2024-10/smart_collections/482865238/order.json?products[]=921728736&products[]=632910392
Copy
curl -d '{}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2024-10/smart_collections/482865238/order.json?products%5B%5D=921728736&products%5B%5D=632910392" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 200 OK
{}
Anchor to section titled 'DELETE request, Removes a smart collection'

del
Removes a smart collection

collectionDelete
Removes a smart collection
Anchor to section titled 'Parameters of Removes a smart collection'

Parameters

api_version
string
required
smart_collection_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Removes a smart collection'

Examples

Path parameters
smartcollectionid=482865238
string
required
Was this section helpful?
del
/admin/api/2024-10/smart_collections/482865238.json
Copy
curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2024-10/smart_collections/482865238.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{}