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'

CustomCollection

Requires products access scope.

A custom collection is a grouping of products that a merchant can create to make their store easier to browse. The merchant creates a custom collection and then selects the products that will go into it.

Collections are typically displayed to customers so that buyers can select to view only the products in the collection. Shopify stores start with a single custom collection called frontpage—the collection of products shown on the front page of the online store.

The Collect resource is used to connect a product to a custom collection.

There are also smart collections, which contain products based on selection conditions rather than because they've been included manually. For more information, see the SmartCollection resource.

Was this section helpful?
Anchor to section titled 'The CustomCollection resource'

The CustomCollection resource

Properties
body_html
->descriptionHtml
The description of the custom collection, complete with HTML markup. Many templates display this on their custom collection pages.
handle
->handle
A human-friendly unique string for the custom collection automatically generated from its title. This is used in shop themes by the Liquid templating language to refer to the custom collection. (limit: 255 characters)
image
->image

Image associated with the custom collection. Valid values are:

id
read-only
->id
The ID for the custom collection.
published
->isPublished
Whether the custom collection is published to the Online Store channel.
published_at
read-only
->publishDate

The time and date (ISO 8601 format) when the collection was made visible. Returns null for a hidden custom collection.

published_scope
read-only
->publishable
Whether the collection is published to the Point of Sale channel. Valid values:
sort_order
->sortOrder

The order in which products in the custom collection appear. Valid values:

template_suffix
->templateSuffix
The suffix of the liquid template being used. For example, if the value is custom, then the collection is using the collection.custom.liquid template. If the value is null, then the collection is using the default collection.liquid.
title
->title
The name of the custom collection. (limit: 255 characters)
updated_at
read-only
->updatedAt
The date and time (ISO 8601 format) when the custom collection was last modified.
Was this section helpful?
{}The CustomCollection resource
{
  "body_html": "<p>The best selling iPods ever</p>",
  "handle": "ipods",
  "image": {
    "src": "http://static.shopify.com/collections/ipod.jpg?0",
    "alt": "iPods",
    "width": 500,
    "height": 488,
    "created_at": "2018-04-19T09:34:47-04:00"
  },
  "id": 841564295,
  "published": true,
  "published_at": "2008-02-01T19:00:00-05:00",
  "published_scope": "global",
  "sort_order": "manual",
  "template_suffix": "custom",
  "title": "IPods",
  "updated_at": "2008-02-01T19:00:00-05:00"
}
Anchor to section titled 'POST request, Creates a custom collection'

post
Creates a custom collection

collectionCreate
Creates a custom collection
Anchor to section titled 'Parameters of Creates a custom collection'

Parameters

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

Examples

Request body
customcollection
Custom_collection resource
Was this section helpful?
post
/admin/api/2024-10/custom_collections.json
Copy
curl -d '{"custom_collection":{"title":"IPods","collects":[{"product_id":921728736}]}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2024-10/custom_collections.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 201 Created
{
  "custom_collection": {
    "id": 1063001333,
    "handle": "ipods-1",
    "title": "IPods",
    "updated_at": "2024-09-24T10:55:02-04:00",
    "body_html": null,
    "published_at": "2024-09-24T10:55:02-04:00",
    "sort_order": "best-selling",
    "template_suffix": null,
    "published_scope": "web",
    "admin_graphql_api_id": "gid://shopify/Collection/1063001333"
  }
}
Anchor to section titled 'GET request, Retrieves a list of custom collections'

get
Retrieves a list of custom collections

collections
Retrieves a list of custom 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 custom collections'

Parameters

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

Examples

Query parameters
ids=395646240691652237841564295
Show only collections specified by a comma-separated list of IDs.
Was this section helpful?
get
/admin/api/2024-10/custom_collections.json?ids=395646240691652237841564295
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/custom_collections.json?ids=395646240%2C691652237%2C841564295" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "custom_collections": [
    {
      "id": 841564295,
      "handle": "ipods",
      "title": "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,
      "published_scope": "web",
      "admin_graphql_api_id": "gid://shopify/Collection/841564295",
      "image": {
        "created_at": "2024-09-24T10:33:18-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=1727188398"
      }
    },
    {
      "id": 395646240,
      "handle": "ipods_two",
      "title": "IPods Two",
      "updated_at": "2008-02-01T19:00:00-05:00",
      "body_html": "<p>The best selling ipod ever. Again</p>",
      "published_at": "2008-02-01T19:00:00-05:00",
      "sort_order": "manual",
      "template_suffix": null,
      "published_scope": "web",
      "admin_graphql_api_id": "gid://shopify/Collection/395646240"
    },
    {
      "id": 691652237,
      "handle": "non-ipods",
      "title": "Non Ipods",
      "updated_at": "2013-02-01T19:00:00-05:00",
      "body_html": "<p>No ipods here</p>",
      "published_at": "2013-02-01T19:00:00-05:00",
      "sort_order": "manual",
      "template_suffix": null,
      "published_scope": "web",
      "admin_graphql_api_id": "gid://shopify/Collection/691652237"
    }
  ]
}
Anchor to section titled 'GET request, Retrieves a single custom collection'

get
Retrieves a single custom collection

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

Parameters

api_version
string
required
custom_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 custom collection'

Examples

Path parameters
customcollectionid=841564295
string
required
Was this section helpful?
get
/admin/api/2024-10/custom_collections/841564295.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/custom_collections/841564295.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "custom_collection": {
    "id": 841564295,
    "handle": "ipods",
    "title": "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": 1,
    "published_scope": "web",
    "admin_graphql_api_id": "gid://shopify/Collection/841564295",
    "image": {
      "created_at": "2024-09-24T10:33:18-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=1727188398"
    }
  }
}
Anchor to section titled 'GET request, Retrieves a count of custom collections'

get
Retrieves a count of custom collections

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

Parameters

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

Examples

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

put
Updates an existing custom collection

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

Parameters

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

Examples

Path parameters
customcollectionid=841564295
string
required
Request body
customcollection
Custom_collection resource
Was this section helpful?
put
/admin/api/2024-10/custom_collections/841564295.json
Copy
curl -d '{"custom_collection":{"id":841564295,"collects":[{"product_id":921728736,"position":1},{"id":455204334,"position":2}]}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2024-10/custom_collections/841564295.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 200 OK
{
  "custom_collection": {
    "title": "IPods",
    "handle": "ipods",
    "body_html": "<p>The best selling ipod ever</p>",
    "id": 841564295,
    "updated_at": "2024-09-24T10:55:11-04:00",
    "published_at": "2008-02-01T19:00:00-05:00",
    "sort_order": "manual",
    "template_suffix": null,
    "published_scope": "web",
    "admin_graphql_api_id": "gid://shopify/Collection/841564295",
    "image": {
      "created_at": "2024-09-24T10:33:18-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=1727188398"
    }
  }
}
Anchor to section titled 'DELETE request, Deletes a custom collection'

del
Deletes a custom collection

collectionDelete
Deletes a custom collection
Anchor to section titled 'Parameters of Deletes a custom collection'

Parameters

api_version
string
required
custom_collection_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Deletes a custom collection'

Examples

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