Skip to main content

The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the GraphQL Admin API. For details and migration steps, visit our migration guide.

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?
#

Endpoints

Anchor to

The CustomCollection resource

Anchor to

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:

Show image properties
  • attachment: An image attached to a custom collection returned as Base64-encoded binary data.
  • src: The source URL that specifies the location of the image.
  • alt: Alternative text that describes the collection image.
  • created_at: The time and date (ISO 8601 format) when the image was added to the collection.
  • width: The width of the image in pixels.
  • height: The height of the image in pixels.
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:

Show published_scope properties
  • web: The custom collection is published to the Online Store channel but not published to the Point of Sale channel.
  • global: The custom collection is published to both the Online Store channel and the Point of Sale channel.
sort_order
->
sortOrder

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

Show sort_order properties
  • alpha-asc: Alphabetically, in ascending order (A - Z).
  • alpha-desc: Alphabetically, in descending order (Z - A).
  • best-selling: By best-selling products.
  • created: By date created, in ascending order (oldest - newest).
  • created-desc: By date created, in descending order (newest - oldest).
  • manual: Order created by the shop owner.
  • price-asc: By price, in ascending order (lowest - highest).
  • price-desc: By price, in descending order (highest - lowest).
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 POST request, Creates a custom collection
post
Creates a custom collection

collectionCreate

Creates a custom collection

Anchor to Parameters of Creates a custom collectionParameters

api_version
string
required
Was this section helpful?

Anchor to post-custom-collections-examplesExamples

Create a collection that contains a product by including a collect

Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.title:"IPods"
->
title

The name of the custom collection. (limit: 255 characters)

Create a custom collection

Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.title:"Macbooks"
->
title

The name of the custom collection. (limit: 255 characters)

Create a custom collection with a metafield

Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.title:"Macbooks"
->
title

The name of the custom collection. (limit: 255 characters)

Create a custom collection with an image, which will be uploaded to Shopify

Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.title:"Macbooks"
->
title

The name of the custom collection. (limit: 255 characters)

custom_collection.image:{"src":"http://example.com/rails_logo.gif","alt":"Rails Logo"}
->
image

Image associated with the custom collection. Valid values are:

Show image properties
  • attachment: An image attached to a custom collection returned as Base64-encoded binary data.
  • src: The source URL that specifies the location of the image.
  • alt: Alternative text that describes the collection image.
  • created_at: The time and date (ISO 8601 format) when the image was added to the collection.
  • width: The width of the image in pixels.
  • height: The height of the image in pixels.

Create an unpublished custom collection

Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.title:"Macbooks"
->
title

The name of the custom collection. (limit: 255 characters)

custom_collection.published:false

Whether the custom collection is published to the Online Store channel.

Creating a custom collection without a title fails and returns an error

Was this section helpful?
post

/admin/api/2025-07/custom_collections.json

curl -d '{"custom_collection":{"title":"IPods","collects":[{"product_id":921728736}]}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2025-07/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": 1063001334,
"handle": "ipods-1",
"title": "IPods",
"updated_at": "2025-07-01T14:40:15-04:00",
"body_html": null,
"published_at": "2025-07-01T14:40:15-04:00",
"sort_order": "best-selling",
"template_suffix": null,
"published_scope": "web",
"admin_graphql_api_id": "gid://shopify/Collection/1063001334"
}
}

Anchor to 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 Parameters of Retrieves a list of custom collectionsParameters

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.

Show published_status properties

  • published: Show only published custom collections.

  • unpublished: Show only unpublished custom collections.

  • any: Show custom collections of any 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 get-custom-collections?ids=395646240,691652237,841564295-examplesExamples

Retrieve a list of specific custom collections

Query parameters
ids=395646240,691652237,841564295

Show only collections specified by a comma-separated list of IDs.

Retrieve all collections

Retrieve all collections after the specified ID

Query parameters
since_id=841564295

Restrict results to after the specified ID.

Retrieve all custom collections that contain a given product

Query parameters
product_id=632910392

Show custom collections that include a given product.

Was this section helpful?
get

/admin/api/2025-07/custom_collections.json?ids=395646240,691652237,841564295

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/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": "2025-07-01T14:37:24-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=1751395044"
}
},
{
"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 GET request, Retrieves a single custom collection
get
Retrieves a single custom collection

collection

Retrieves a single custom collection

Anchor to Parameters of Retrieves a single custom collectionParameters

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 get-custom-collections-custom-collection-id-examplesExamples

Retrieve a specific collection by its ID

Path parameters
custom_collection_id=841564295
string
required
Was this section helpful?
get

/admin/api/2025-07/custom_collections/841564295.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/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": "2025-07-01T14:37:24-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=1751395044"
}
}
}

Anchor to GET request, Retrieves a count of custom collections
get
Retrieves a count of custom collections

collectionsCount

Retrieves a count of custom collections

Anchor to Parameters of Retrieves a count of custom collectionsParameters

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.

Show published_status properties

  • published: Count only published custom collections.

  • unpublished: Count only unpublished custom collections.

  • any: Count custom collections of any 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 get-custom-collections-count-examplesExamples

Count all custom collections

Count all custom collections that contain a given product

Query parameters
product_id=632910392

Count custom collections that include a given product.

Was this section helpful?
get

/admin/api/2025-07/custom_collections/count.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/custom_collections/count.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"count": 3
}

Anchor to PUT request, Updates an existing custom collection
put
Updates an existing custom collection

collectionUpdate

Updates an existing custom collection

Anchor to Parameters of Updates an existing custom collectionParameters

api_version
string
required
custom_collection_id
string
required
Was this section helpful?

Anchor to put-custom-collections-custom-collection-id-examplesExamples

Add a collect to an existing collection by providing a product ID, and update an existing collect by its own ID to change its sort position

Path parameters
custom_collection_id=841564295
string
required
Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.id:841564295
read-only

The ID for the custom collection.

Add a metafield to an existing collection

Path parameters
custom_collection_id=841564295
string
required
Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.id:841564295
read-only

The ID for the custom collection.

Hide a published collection

Path parameters
custom_collection_id=841564295
string
required
Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.id:841564295
read-only

The ID for the custom collection.

custom_collection.published:false

Whether the custom collection is published to the Online Store channel.

Publish a hidden collection

Path parameters
custom_collection_id=841564295
string
required
Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.id:841564295
read-only

The ID for the custom collection.

custom_collection.published:true

Whether the custom collection is published to the Online Store channel.

Update a collection to remove its image

Path parameters
custom_collection_id=841564295
string
required
Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.id:841564295
read-only

The ID for the custom collection.

custom_collection.image:""
->
image

Image associated with the custom collection. Valid values are:

Show image properties
  • attachment: An image attached to a custom collection returned as Base64-encoded binary data.
  • src: The source URL that specifies the location of the image.
  • alt: Alternative text that describes the collection image.
  • created_at: The time and date (ISO 8601 format) when the image was added to the collection.
  • width: The width of the image in pixels.
  • height: The height of the image in pixels.
custom_collection.updated_at:"2025-07-01T14:39:45-04:00"
read-only

The date and time (ISO 8601 format) when the custom collection was last modified.

custom_collection.handle:"ipods"
->
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)

custom_collection.title:"IPods"
->
title

The name of the custom collection. (limit: 255 characters)

custom_collection.body_html:"<p>The best selling ipod ever</p>"
->
descriptionHtml

The description of the custom collection, complete with HTML markup. Many templates display this on their custom collection pages.

custom_collection.published_at:"2008-02-01T19:00:00-05:00"
read-only

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

custom_collection.sort_order:"manual"
->
sortOrder

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

Show sort_order properties
  • alpha-asc: Alphabetically, in ascending order (A - Z).
  • alpha-desc: Alphabetically, in descending order (Z - A).
  • best-selling: By best-selling products.
  • created: By date created, in ascending order (oldest - newest).
  • created-desc: By date created, in descending order (newest - oldest).
  • manual: Order created by the shop owner.
  • price-asc: By price, in ascending order (lowest - highest).
  • price-desc: By price, in descending order (highest - lowest).
custom_collection.template_suffix:null
->
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.

custom_collection.published_scope:"web"
read-only

Whether the collection is published to the Point of Sale channel. Valid values:

Show published_scope properties
  • web: The custom collection is published to the Online Store channel but not published to the Point of Sale channel.
  • global: The custom collection is published to both the Online Store channel and the Point of Sale channel.

Update a collection with a new collection image

Path parameters
custom_collection_id=841564295
string
required
Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.id:841564295
read-only

The ID for the custom collection.

custom_collection.image:{"attachment":"R0lGODlhbgCMAPf/APbr48VySrxTO7IgKt2qmKQdJeK8lsFjROG5p/nz7Zg3\nMNmnd7Q1MLNVS9GId71hSJMZIuzTu4UtKbeEeakhKMl8U8WYjfr18YQaIbAf\nKKwhKdKzqpQtLebFortOOejKrOjZ1Mt7aMNpVbAqLLV7bsNqR+3WwMqEWenN\nsZYxL/Ddy/Pm2e7ZxLlUQrIjNPXp3bU5MbhENbEtLtqhj5ZQTfHh0bMxL7Ip\nNsNyUYkZIrZJPcqGdYIUHb5aPKkeJnoUHd2yiJkiLKYiKLRFOsyJXKVDO8up\nosFaS+TBnK4kKti5sNaYg/z49aqYl5kqLrljUtORfMOlo/36+H4ZH8yDYq0f\nKKFYTaU9MrY8MrZBNXwXHpgaIdGVYu/byLZNP9SaZLIyOuXCtHkpJst+Wpcm\nLMyCa8BfP9GMb9KQdPDd1PPk1sd5VP79/L5dQZ0bI9+ymqssK9WcfIoXHdzG\nxdWWfteib79lSr1YP86MYurQxKdcUKdMQr5ZSfPs6YEZH8uhl4oWIenMuurQ\nttmejaqoqsqBVaAcJLlJN5kvMLlZRMNsSL5fRak0LbdQQMVvSPjw6cJnRpkf\nKtmjhvfu5cJtT7IuOMVvWLY/M/37+o0YH9ibhtSYdObErc6HarM9NnYSGNGR\navLi09unje3WyeO8rsVrT7tdRtK3uffu6NWeaL9pTJIjJrM4NPbx8cdyX7M7\nPYYVHu7j4KgoNJAYIKtkV5o9MsOcldicis+RYNutfrhFOZ0hJbqinZ8bI8h5\nUObFuOfItJsfJrJfUOfIqc+PXqQtK8RnSbA4Mcd3Tm0SGbpXQ8aqp7RLNs+s\novHfzpVhV9iggMd1TLtbRKUdKXEQFsd4XrZRPLIgMZUeJ+jKvrAlK6AhJ65A\nMpMpKuC3j5obIsRwS7hAN8l/YtvDvnYXHbAoLI47SIUsOMenorF4gO/m4+fH\npo4vLZ8oKMukqp0cJbhVSMV2UuPR0bAfMLIrLrg/OcJwT8h+Vt+wn8eurLlh\nQrIfKHQOHHQOHf///////yH5BAEAAP8ALAAAAABuAIwAAAj/AP8JHDhQXjpz\n/PopXNiPn0OHDRMmbKhQIsOJFS1SxAhxI8SHFzVeDBnx48iNBAeeOkcxokeX\nFRdOnAlSokaaLXNujJkxo8iYHRkKtWkzZSsaOXkAWsoUECynsHgoqEW1qtVa\n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\nGg4lOnRGDKRZsoS7pMPSA6YXNWLsKJLkSZOVwKhMGSTTrJf9ZNKcomXKTrQY\nevr02cSIvKJxi6aJkaVuXaZMs1ziO5UqPawnuXK9AWEW2Jhja9pMuzMd27YW\nLNga10fuZYUPkdZdqpTv575YbJQbkCHw1sEpb9wQMstwWLFkbfppjJPc/wTI\nhHhJ5r0BBGbMRzfb7ez5MwwbpTMsx5pa9eob2CBM5yETpmzGtTE8hrybN29b\nc1oBn6trc9K7nhmUy6BcOUrn0KHLcr0FQvWYMxdnb3w7t/fvwFMiFvKG0uw8\n4kRLYjkGG0RtMPlWc+GGdyCwbwtYrOsHu7K0a+K/AEO04K0CF8InBvPOg2GE\nKpZTrsHSUotwwgnnmW4LHGGBKbb9bMqhsSly082CW0QMkDLLSvQHFQFiOESX\nLGzQpkUY22swA8Lko9EFLqfBEcdvMhRrwx610OLHtJ5Rc01ahHnCzTeFkXNO\nOfWQkwQ6NNFzTz2X0GQJQAMVdJEYsBhBAyrbK/9tgBcbrCTCG7bkkstvvvwm\nzPzI7JEcNLXDCYICQhXVkAIMMdWQd0x1Y9VdiuHGA1hjhfWQQzyg9dZDYmBg\nyioSVfRKFwfYZ8ZIJ3XhGhe83OLSSwEZU78ea+pUO2wK8MFaUUMl9dReDOll\n1VXbuYIZWWOl1dZDLpGhV3YZXLTR9vZhUMJijUX2mmveYRZcQDLlsCZOp21s\nCx+uLTjbbE/11ttv3diFkSHKRReGcthtN1hgrdxH2Awk5fJefK+ZZ9lvVvXW\n2cT+ZSwHgdHCpmCYDb4WYVNL7baXbsN9FdYYbKDA4otddBdYeffZx9iPjw35\nmmlKNtnUfmXSNNqAW9b/6eWYY8YWYW0V7tYQhxWAwwege61y6OXkbdDoSUFe\nWuR3wP3akKhjUtlHlqklG+YqsjaY620VNgQDMcQQouwrX3zR6KKFZfttyKtw\n+utQnRUL2mjLYjnvtLDpu9e9/ZYZ8FK3maLwwn8OmlF3lWNc7df3gfzteaZZ\n+NTKx5y6RxJ69/333mvBwHOLQ/fhiR2SV34HS47hmnAafJ9gh3AaDMcB7LE/\nIoPY441dhOzDz94VN3DPNmoeM5drAyfK7lWH34baYetVCidBIT6C5UMhB4r2\nn3FheSANRVGCwhBmObtlbgqXyYYNyuYFAMQFCtPwQf3spxAraGBRR+Af91wX\n/zsPoCIuCCAV13yAMsWo7zIOaJHFSHEZHZABdWK4X0JoIAENLIeDCXFA2rgX\nuwG8MC6kKGGoZuaDTEhtd/vBTBoyYLYqeAEzFpihGCagEBqIQQJVGMAOEdLD\n2L0uHJdBAMIOhsTELHExwLnS/i6zAQlIQItWxKIccejGL/4wjPvw4kHSQApA\nBhKQUDCiEWE2C93dTSEW2EMjaWABhbgnA3g8SAj4cElK+kMJWoyjBK6YECtw\nUgKZ7N8ejdZHfzjgGgNY5SpnZsisJXFHikwICTLBskzUECFtxJ/FFKKETmrx\nkwixQiclYAX+mfKUCpnBEZzpzHpkS2Yxm0ViMNcjhf+QABs5uKUuD9KoTOaP\nQb80picxaExk8lCZfIxLNuBhrWnurZpjoiVCbAkBbnrTH2pbTjgZVAVyGnOY\nBylmJ9P5xXWOUS6WEB3ZqgmTazLxMk40WntQub3lbIOc7OjkQP1RUI4e9CCl\nfJ3jjCbEogDAE6KrAiKlVs+4gJF7GUDlDLLnUWCyg6Ps8GgxdyrSVK5zH/WI\noARjZjFEQhSmRCEFg9SGSqIoQadT7alOJcAOoJJUmeFA6VBIETqk+ssPKizK\nDorxwx9CdShSvapOqzpVoO7ApMocgAdcIb74HeSroEOqEn8w1mgVRR0KyEEw\nKqoctTZEquzggFsVooepskP/DwqZAAfmakpGvc4HXSXF54CWVLthALASRYhB\nFpmDd4QxsQxRQmNd61HITnWyCVHC9MTnCsY9U7dH4AM8spGQvVrsiRB4Fg/8\ncFxsJmQDHvUHLQyhWsy01rXs2MFj2ZGC6862KKRgHGY6K9zlEPdyP8AJcteo\n3ClsQCHq0AF0QdkN+HbjlxygL31hO13tMrW7lwkB0BiUoR3x4EfmrYlCNjAF\nCRAoIWmwQexQqQcyxHe+9eXAfVOQAg7k16v7jQsAHGi2Bv0gUzyQQ05Ga+Cy\n0MBEDsZgN8gQ4QnXt7oJ0QOGOZACDTeEu0aTCwC80EKhDcAHMDGHWATMsuMC\nFsVl/9GnP0Jg0kw24MUv/qUTOGDlCj8WETfGsVx2vI+UzsATIFZUaTIRk3QY\n+ZYlFq0Ce5QJHBXgdU+MRCSwEYlVBCHPQZhyn7vhhD9fWdAc2DKhKXxhRCc6\n0Yi4LOPcl6hGVUFqc4gJLGaxufKO1s2VkrOj63znOkciCKMedZ+n7ARUp1rQ\niLAyIlyNYURcONaInrWs9ci4JyJOaFYawDzP8Q+ZwAICLckbgd08i290eh9V\nCIadQw3qO5Oa1H1GNRlSjeorO2HLruZ2rLudAm+Dm9Gxcx/GXmSIMbnjH5W2\nzy2RbOzM+cENBRAWs0N9b3zXWdp8pra1r61tbXdb4N/2Nv8i5gzeIJd5Gjui\nwT+AzQ9YVGrYnNO0Agm27GBkvNnNzje+921qf/+b1QEfuMDFPe5lk/lspUG3\nWKbQCofLBBBuwNEs3C3aikcrB2TTeM81HgmOd3zf/PZ3yFPNaqSXfODF0EDK\nE9e6liZmCvJwOLD7AQhU2efSbG6zm7VgiG1ofBc+//nGgZ7vbYw67aVux4v/\nfXSSK53by/HVrzIwDZTBBANUrzpMeAAIWASeB4P/AQ9+cHjEJx7xWgDE5nLQ\neMdHXvKbg/zkMZ23H/1oFRjYPOc9v3nQ58Aw0xn9LACvO7HQAOZVf/jl0ii1\nHcXe9bPX3euftaPL5R71tIf97nsy7/o0WlP2r4/JOU7B+r5nqva7jz1EdZ97\n4qNe+bonfvCfVXvly1762beOOdLBd+Q7PCAAOw==\n","alt":"Rails logo"}
->
image

Image associated with the custom collection. Valid values are:

Show image properties
  • attachment: An image attached to a custom collection returned as Base64-encoded binary data.
  • src: The source URL that specifies the location of the image.
  • alt: Alternative text that describes the collection image.
  • created_at: The time and date (ISO 8601 format) when the image was added to the collection.
  • width: The width of the image in pixels.
  • height: The height of the image in pixels.

Update a collection with new alt text for its image

Path parameters
custom_collection_id=841564295
string
required
Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.id:841564295
read-only

The ID for the custom collection.

custom_collection.image:{"alt":"Rails logo"}
->
image

Image associated with the custom collection. Valid values are:

Show image properties
  • attachment: An image attached to a custom collection returned as Base64-encoded binary data.
  • src: The source URL that specifies the location of the image.
  • alt: Alternative text that describes the collection image.
  • created_at: The time and date (ISO 8601 format) when the image was added to the collection.
  • width: The width of the image in pixels.
  • height: The height of the image in pixels.

Update the description of a custom collection

Path parameters
custom_collection_id=841564295
string
required
Request body
custom_collection
Custom_collection resource
Show custom_collection properties
custom_collection.id:841564295
read-only

The ID for the custom collection.

custom_collection.body_html:"<p>5000 songs in your pocket</p>"
->
descriptionHtml

The description of the custom collection, complete with HTML markup. Many templates display this on their custom collection pages.

Was this section helpful?
put

/admin/api/2025-07/custom_collections/841564295.json

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/2025-07/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": "2025-07-01T14:39:47-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": "2025-07-01T14:37:24-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=1751395044"
}
}
}

Anchor to DELETE request, Deletes a custom collection
del
Deletes a custom collection

collectionDelete

Deletes a custom collection

Anchor to Parameters of Deletes a custom collectionParameters

api_version
string
required
custom_collection_id
string
required
Was this section helpful?

Anchor to delete-custom-collections-custom-collection-id-examplesExamples

Delete a custom collection

Path parameters
custom_collection_id=841564295
string
required
Was this section helpful?
del

/admin/api/2025-07/custom_collections/841564295.json

curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2025-07/custom_collections/841564295.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{}