CollectionListing

Version 2019-04

Sales Channel SDK

The CollectionListing resource is available to Sales Channel SDK applications only.

A CollectionListing resource represents a product collection that a merchant has made available to your sales channel. Merchants can make collections available to your sales channel directly from their Shopify admin.

You can use this resource to retrieve collections that a merchant has published and display them in your marketplace. You can also retrieve a list of published product IDs that belong to a published collection.

Note:

When a merchant makes a collection available to your app, the products belonging to that collection are not automatically made available. The merchant must make both the collection and each product available to your sales channel.

What you can do with CollectionListing

The Shopify API lets you do the following with the CollectionListing resource. More detailed versions of these general actions may be available:

CollectionListing properties

collection_id
read-only 
"collection_id": 1053727709

Identifies which collection this listing is for.
body_html
read-only 
"body_html": "It's a collection of curated products for the home page."

The description of the collection, complete with HTML formatting.
default_product_image
read-only 
"default_product_image": [
  {
    "src": "http://example.com/burton.jpg"
  }
]

The default product image for a collection.
image
read-only 
"image": [
  {
    "src": "http://example.com/burton.jpg"
  }
]

The image for a collection.
handle
read-only 
"handle": "ipod-nano"

A human-friendly unique string for the Collection automatically generated from its title.
published_at
read-only 
"published_at": "2007-12-31T19:00:00-05:00"

The date and time when the collection was published. The API returns this in ISO_8601.
title
read-only 
"title": "Home page"

The name of the collection.
sort_order
read-only 
"sort_order": "alpha-asc"

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

  • 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).
updated_at
read-only 
"updated_at": "2012-08-24T14:01:47-04:00"

The date and time when the collection was last modified. The API returns this in ISO_8601.

Endpoints

GET /admin/api/2019-04/collection_listings.json
Retrieve collection listings that are published to your app. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

Amount of results

(default: 50, maximum: 1000)
page
deprecated

The page of results to show.

(default: 1)

Retrieve collection listings that are published to your app

GET /admin/api/2019-04/collection_listings.json
View Response 
HTTP/1.1 200 OK
{
  "collection_listings": [
    {
      "collection_id": 482865238,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever</p>",
      "default_product_image": null,
      "handle": "smart-ipods",
      "image": {
        "created_at": "2020-02-06T12:33:39-05:00",
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
      },
      "title": "Smart iPods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 841564295,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever</p>",
      "default_product_image": null,
      "handle": "ipods",
      "image": {
        "created_at": "2020-02-06T12:33:39-05:00",
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
      },
      "title": "IPods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 395646240,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever. Again</p>",
      "default_product_image": {
        "id": 850703190,
        "created_at": "2020-02-06T12:33:39-05:00",
        "position": 1,
        "updated_at": "2020-02-06T12:33:39-05:00",
        "product_id": 632910392,
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/products/ipod-nano.png?v=1581010419",
        "variant_ids": [],
        "width": 123,
        "height": 456
      },
      "handle": "ipods_two",
      "image": null,
      "title": "IPods Two",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 691652237,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>No ipods here</p>",
      "default_product_image": null,
      "handle": "non-ipods",
      "image": null,
      "title": "Non Ipods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    }
  ]
}
GET /admin/api/2019-04/collection_listings/#{collection_listing_id}/product_ids.json
Retrieve product_ids that are published to a collection_id. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

Amount of results

(default: 50, maximum: 1000)
page
deprecated

The page of results to show.

(default: 1)

Retrieve product_ids that are published to a collection_id

GET /admin/api/2019-04/collection_listings/#{collection_listing_id}/product_ids.json
View Response 
HTTP/1.1 200 OK
{
  "product_ids": [
    632910392
  ]
}
GET /admin/api/2019-04/collection_listings/#{collection_listing_id}.json
Retrieve a specific collection listing that is published to your app

Retrieve a specific collection listing that is published to your app

GET /admin/api/2019-04/collection_listings/#{collection_listing_id}.json
View Response 
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2020-02-06T12:33:39-05:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2020-02-06T12:33:39-05:00",
      "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-08-31T20:00:00-04:00"
  }
}
PUT /admin/api/2019-04/collection_listings/#{collection_listing_id}.json
Create a collection listing to publish a collection to your app

Create a collection listing to publish a collection to your app

PUT /admin/api/2019-04/collection_listings/#{collection_listing_id}.json
{
  "collection_listing": {
    "collection_id": 482865238
  }
}
View Response 
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2020-02-06T12:33:39-05:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2020-02-06T12:33:39-05:00",
      "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-08-31T20:00:00-04:00"
  }
}
DELETE /admin/api/2019-04/collection_listings/#{collection_listing_id}.json
Delete a collection listing to unpublish a collection from your app

Delete a collection listing to unpublish a collection from your app

DELETE /admin/api/2019-04/collection_listings/#{collection_listing_id}.json
View Response 
HTTP/1.1 200 OK
Version 2019-07

Sales Channel SDK

The CollectionListing resource is available to Sales Channel SDK applications only.

A CollectionListing resource represents a product collection that a merchant has made available to your sales channel. Merchants can make collections available to your sales channel directly from their Shopify admin.

You can use this resource to retrieve collections that a merchant has published and display them in your marketplace. You can also retrieve a list of published product IDs that belong to a published collection.

Note:

When a merchant makes a collection available to your app, the products belonging to that collection are not automatically made available. The merchant must make both the collection and each product available to your sales channel.

What you can do with CollectionListing

The Shopify API lets you do the following with the CollectionListing resource. More detailed versions of these general actions may be available:

CollectionListing properties

collection_id
read-only 
"collection_id": 1053727709

Identifies which collection this listing is for.
body_html
read-only 
"body_html": "It's a collection of curated products for the home page."

The description of the collection, complete with HTML formatting.
default_product_image
read-only 
"default_product_image": [
  {
    "src": "http://example.com/burton.jpg"
  }
]

The default product image for a collection.
image
read-only 
"image": [
  {
    "src": "http://example.com/burton.jpg"
  }
]

The image for a collection.
handle
read-only 
"handle": "ipod-nano"

A human-friendly unique string for the Collection automatically generated from its title.
published_at
read-only 
"published_at": "2007-12-31T19:00:00-05:00"

The date and time when the collection was published. The API returns this in ISO_8601.
title
read-only 
"title": "Home page"

The name of the collection.
sort_order
read-only 
"sort_order": "alpha-asc"

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

  • 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).
updated_at
read-only 
"updated_at": "2012-08-24T14:01:47-04:00"

The date and time when the collection was last modified. The API returns this in ISO_8601.

Endpoints

GET /admin/api/2019-07/collection_listings.json
Retrieve collection listings that are published to your app. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

Amount of results

(default: 50, maximum: 1000)

Retrieve collection listings that are published to your app

GET /admin/api/2019-07/collection_listings.json
View Response 
HTTP/1.1 200 OK
{
  "collection_listings": [
    {
      "collection_id": 482865238,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever</p>",
      "default_product_image": null,
      "handle": "smart-ipods",
      "image": {
        "created_at": "2020-02-06T12:33:39-05:00",
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
      },
      "title": "Smart iPods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 841564295,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever</p>",
      "default_product_image": null,
      "handle": "ipods",
      "image": {
        "created_at": "2020-02-06T12:33:39-05:00",
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
      },
      "title": "IPods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 395646240,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever. Again</p>",
      "default_product_image": {
        "id": 850703190,
        "created_at": "2020-02-06T12:33:39-05:00",
        "position": 1,
        "updated_at": "2020-02-06T12:33:39-05:00",
        "product_id": 632910392,
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/products/ipod-nano.png?v=1581010419",
        "variant_ids": [],
        "width": 123,
        "height": 456
      },
      "handle": "ipods_two",
      "image": null,
      "title": "IPods Two",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 691652237,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>No ipods here</p>",
      "default_product_image": null,
      "handle": "non-ipods",
      "image": null,
      "title": "Non Ipods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    }
  ]
}
GET /admin/api/2019-07/collection_listings/#{collection_listing_id}/product_ids.json
Retrieve product_ids that are published to a collection_id. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

Amount of results

(default: 50, maximum: 1000)

Retrieve product_ids that are published to a collection_id

GET /admin/api/2019-07/collection_listings/#{collection_listing_id}/product_ids.json
View Response 
HTTP/1.1 200 OK
{
  "product_ids": [
    632910392
  ]
}
GET /admin/api/2019-07/collection_listings/#{collection_listing_id}.json
Retrieve a specific collection listing that is published to your app

Retrieve a specific collection listing that is published to your app

GET /admin/api/2019-07/collection_listings/#{collection_listing_id}.json
View Response 
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2020-02-06T12:33:39-05:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2020-02-06T12:33:39-05:00",
      "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-08-31T20:00:00-04:00"
  }
}
PUT /admin/api/2019-07/collection_listings/#{collection_listing_id}.json
Create a collection listing to publish a collection to your app

Create a collection listing to publish a collection to your app

PUT /admin/api/2019-07/collection_listings/#{collection_listing_id}.json
{
  "collection_listing": {
    "collection_id": 482865238
  }
}
View Response 
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2020-02-06T12:33:39-05:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2020-02-06T12:33:39-05:00",
      "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-08-31T20:00:00-04:00"
  }
}
DELETE /admin/api/2019-07/collection_listings/#{collection_listing_id}.json
Delete a collection listing to unpublish a collection from your app

Delete a collection listing to unpublish a collection from your app

DELETE /admin/api/2019-07/collection_listings/#{collection_listing_id}.json
View Response 
HTTP/1.1 200 OK
Version 2019-10

Sales Channel SDK

The CollectionListing resource is available to Sales Channel SDK applications only.

A CollectionListing resource represents a product collection that a merchant has made available to your sales channel. Merchants can make collections available to your sales channel directly from their Shopify admin.

You can use this resource to retrieve collections that a merchant has published and display them in your marketplace. You can also retrieve a list of published product IDs that belong to a published collection.

Note:

When a merchant makes a collection available to your app, the products belonging to that collection are not automatically made available. The merchant must make both the collection and each product available to your sales channel.

What you can do with CollectionListing

The Shopify API lets you do the following with the CollectionListing resource. More detailed versions of these general actions may be available:

CollectionListing properties

collection_id
read-only 
"collection_id": 1053727709

Identifies which collection this listing is for.
body_html
read-only 
"body_html": "It's a collection of curated products for the home page."

The description of the collection, complete with HTML formatting.
default_product_image
read-only 
"default_product_image": [
  {
    "src": "http://example.com/burton.jpg"
  }
]

The default product image for a collection.
image
read-only 
"image": [
  {
    "src": "http://example.com/burton.jpg"
  }
]

The image for a collection.
handle
read-only 
"handle": "ipod-nano"

A human-friendly unique string for the Collection automatically generated from its title.
published_at
read-only 
"published_at": "2007-12-31T19:00:00-05:00"

The date and time when the collection was published. The API returns this in ISO_8601.
title
read-only 
"title": "Home page"

The name of the collection.
sort_order
read-only 
"sort_order": "alpha-asc"

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

  • 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).
updated_at
read-only 
"updated_at": "2012-08-24T14:01:47-04:00"

The date and time when the collection was last modified. The API returns this in ISO_8601.

Endpoints

GET /admin/api/2019-10/collection_listings.json
Retrieve collection listings that are published to your app. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

Amount of results

(default: 50, maximum: 1000)

Retrieve collection listings that are published to your app

GET /admin/api/2019-10/collection_listings.json
View Response 
HTTP/1.1 200 OK
{
  "collection_listings": [
    {
      "collection_id": 482865238,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever</p>",
      "default_product_image": null,
      "handle": "smart-ipods",
      "image": {
        "created_at": "2020-02-06T12:33:39-05:00",
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
      },
      "title": "Smart iPods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 841564295,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever</p>",
      "default_product_image": null,
      "handle": "ipods",
      "image": {
        "created_at": "2020-02-06T12:33:39-05:00",
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
      },
      "title": "IPods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 395646240,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever. Again</p>",
      "default_product_image": {
        "id": 850703190,
        "created_at": "2020-02-06T12:33:39-05:00",
        "position": 1,
        "updated_at": "2020-02-06T12:33:39-05:00",
        "product_id": 632910392,
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/products/ipod-nano.png?v=1581010419",
        "variant_ids": [],
        "width": 123,
        "height": 456
      },
      "handle": "ipods_two",
      "image": null,
      "title": "IPods Two",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 691652237,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>No ipods here</p>",
      "default_product_image": null,
      "handle": "non-ipods",
      "image": null,
      "title": "Non Ipods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    }
  ]
}
GET /admin/api/2019-10/collection_listings/#{collection_listing_id}/product_ids.json
Retrieve product_ids that are published to a collection_id. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

Amount of results

(default: 50, maximum: 1000)

Retrieve product_ids that are published to a collection_id

GET /admin/api/2019-10/collection_listings/#{collection_listing_id}/product_ids.json
View Response 
HTTP/1.1 200 OK
{
  "product_ids": [
    632910392
  ]
}
GET /admin/api/2019-10/collection_listings/#{collection_listing_id}.json
Retrieve a specific collection listing that is published to your app

Retrieve a specific collection listing that is published to your app

GET /admin/api/2019-10/collection_listings/#{collection_listing_id}.json
View Response 
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2020-02-06T12:33:39-05:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2020-02-06T12:33:39-05:00",
      "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-08-31T20:00:00-04:00"
  }
}
PUT /admin/api/2019-10/collection_listings/#{collection_listing_id}.json
Create a collection listing to publish a collection to your app

Create a collection listing to publish a collection to your app

PUT /admin/api/2019-10/collection_listings/#{collection_listing_id}.json
{
  "collection_listing": {
    "collection_id": 482865238
  }
}
View Response 
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2020-02-06T12:33:39-05:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2020-02-06T12:33:39-05:00",
      "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-08-31T20:00:00-04:00"
  }
}
DELETE /admin/api/2019-10/collection_listings/#{collection_listing_id}.json
Delete a collection listing to unpublish a collection from your app

Delete a collection listing to unpublish a collection from your app

DELETE /admin/api/2019-10/collection_listings/#{collection_listing_id}.json
View Response 
HTTP/1.1 200 OK
Version 2020-01 (Latest)

Sales Channel SDK

The CollectionListing resource is available to Sales Channel SDK applications only.

A CollectionListing resource represents a product collection that a merchant has made available to your sales channel. Merchants can make collections available to your sales channel directly from their Shopify admin.

You can use this resource to retrieve collections that a merchant has published and display them in your marketplace. You can also retrieve a list of published product IDs that belong to a published collection.

Note:

When a merchant makes a collection available to your app, the products belonging to that collection are not automatically made available. The merchant must make both the collection and each product available to your sales channel.

What you can do with CollectionListing

The Shopify API lets you do the following with the CollectionListing resource. More detailed versions of these general actions may be available:

CollectionListing properties

collection_id
read-only 
"collection_id": 1053727709

Identifies which collection this listing is for.
body_html
read-only 
"body_html": "It's a collection of curated products for the home page."

The description of the collection, complete with HTML formatting.
default_product_image
read-only 
"default_product_image": [
  {
    "src": "http://example.com/burton.jpg"
  }
]

The default product image for a collection.
image
read-only 
"image": [
  {
    "src": "http://example.com/burton.jpg"
  }
]

The image for a collection.
handle
read-only 
"handle": "ipod-nano"

A human-friendly unique string for the Collection automatically generated from its title.
published_at
read-only 
"published_at": "2007-12-31T19:00:00-05:00"

The date and time when the collection was published. The API returns this in ISO_8601.
title
read-only 
"title": "Home page"

The name of the collection.
sort_order
read-only 
"sort_order": "alpha-asc"

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

  • 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).
updated_at
read-only 
"updated_at": "2012-08-24T14:01:47-04:00"

The date and time when the collection was last modified. The API returns this in ISO_8601.

Endpoints

GET /admin/api/2020-01/collection_listings.json
Retrieve collection listings that are published to your app. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

Amount of results

(default: 50, maximum: 1000)

Retrieve collection listings that are published to your app

GET /admin/api/2020-01/collection_listings.json
View Response 
HTTP/1.1 200 OK
{
  "collection_listings": [
    {
      "collection_id": 482865238,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever</p>",
      "default_product_image": null,
      "handle": "smart-ipods",
      "image": {
        "created_at": "2020-02-06T12:33:39-05:00",
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
      },
      "title": "Smart iPods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 841564295,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever</p>",
      "default_product_image": null,
      "handle": "ipods",
      "image": {
        "created_at": "2020-02-06T12:33:39-05:00",
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
      },
      "title": "IPods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 395646240,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever. Again</p>",
      "default_product_image": {
        "id": 850703190,
        "created_at": "2020-02-06T12:33:39-05:00",
        "position": 1,
        "updated_at": "2020-02-06T12:33:39-05:00",
        "product_id": 632910392,
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/products/ipod-nano.png?v=1581010419",
        "variant_ids": [],
        "width": 123,
        "height": 456
      },
      "handle": "ipods_two",
      "image": null,
      "title": "IPods Two",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 691652237,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>No ipods here</p>",
      "default_product_image": null,
      "handle": "non-ipods",
      "image": null,
      "title": "Non Ipods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    }
  ]
}
GET /admin/api/2020-01/collection_listings/#{collection_listing_id}/product_ids.json
Retrieve product_ids that are published to a collection_id. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

Amount of results

(default: 50, maximum: 1000)

Retrieve product_ids that are published to a collection_id

GET /admin/api/2020-01/collection_listings/#{collection_listing_id}/product_ids.json
View Response 
HTTP/1.1 200 OK
{
  "product_ids": [
    632910392
  ]
}
GET /admin/api/2020-01/collection_listings/#{collection_listing_id}.json
Retrieve a specific collection listing that is published to your app

Retrieve a specific collection listing that is published to your app

GET /admin/api/2020-01/collection_listings/#{collection_listing_id}.json
View Response 
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2020-02-06T12:33:39-05:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2020-02-06T12:33:39-05:00",
      "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-08-31T20:00:00-04:00"
  }
}
PUT /admin/api/2020-01/collection_listings/#{collection_listing_id}.json
Create a collection listing to publish a collection to your app

Create a collection listing to publish a collection to your app

PUT /admin/api/2020-01/collection_listings/#{collection_listing_id}.json
{
  "collection_listing": {
    "collection_id": 482865238
  }
}
View Response 
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2020-02-06T12:33:39-05:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2020-02-06T12:33:39-05:00",
      "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-08-31T20:00:00-04:00"
  }
}
DELETE /admin/api/2020-01/collection_listings/#{collection_listing_id}.json
Delete a collection listing to unpublish a collection from your app

Delete a collection listing to unpublish a collection from your app

DELETE /admin/api/2020-01/collection_listings/#{collection_listing_id}.json
View Response 
HTTP/1.1 200 OK
Version 2020-04 (Release candidate)

Sales Channel SDK

The CollectionListing resource is available to Sales Channel SDK applications only.

A CollectionListing resource represents a product collection that a merchant has made available to your sales channel. Merchants can make collections available to your sales channel directly from their Shopify admin.

You can use this resource to retrieve collections that a merchant has published and display them in your marketplace. You can also retrieve a list of published product IDs that belong to a published collection.

Note:

When a merchant makes a collection available to your app, the products belonging to that collection are not automatically made available. The merchant must make both the collection and each product available to your sales channel.

What you can do with CollectionListing

The Shopify API lets you do the following with the CollectionListing resource. More detailed versions of these general actions may be available:

CollectionListing properties

collection_id
read-only 
"collection_id": 1053727709

Identifies which collection this listing is for.
body_html
read-only 
"body_html": "It's a collection of curated products for the home page."

The description of the collection, complete with HTML formatting.
default_product_image
read-only 
"default_product_image": [
  {
    "src": "http://example.com/burton.jpg"
  }
]

The default product image for a collection.
image
read-only 
"image": [
  {
    "src": "http://example.com/burton.jpg"
  }
]

The image for a collection.
handle
read-only 
"handle": "ipod-nano"

A human-friendly unique string for the Collection automatically generated from its title.
published_at
read-only 
"published_at": "2007-12-31T19:00:00-05:00"

The date and time when the collection was published. The API returns this in ISO_8601.
title
read-only 
"title": "Home page"

The name of the collection.
sort_order
read-only 
"sort_order": "alpha-asc"

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

  • 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).
updated_at
read-only 
"updated_at": "2012-08-24T14:01:47-04:00"

The date and time when the collection was last modified. The API returns this in ISO_8601.

Endpoints

GET /admin/api/2020-04/collection_listings.json
Retrieve collection listings that are published to your app. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

Amount of results

(default: 50, maximum: 1000)

Retrieve collection listings that are published to your app

GET /admin/api/2020-04/collection_listings.json
View Response 
HTTP/1.1 200 OK
{
  "collection_listings": [
    {
      "collection_id": 482865238,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever</p>",
      "default_product_image": null,
      "handle": "smart-ipods",
      "image": {
        "created_at": "2020-02-06T12:33:39-05:00",
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
      },
      "title": "Smart iPods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 841564295,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever</p>",
      "default_product_image": null,
      "handle": "ipods",
      "image": {
        "created_at": "2020-02-06T12:33:39-05:00",
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
      },
      "title": "IPods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 395646240,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>The best selling ipod ever. Again</p>",
      "default_product_image": {
        "id": 850703190,
        "created_at": "2020-02-06T12:33:39-05:00",
        "position": 1,
        "updated_at": "2020-02-06T12:33:39-05:00",
        "product_id": 632910392,
        "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/products/ipod-nano.png?v=1581010419",
        "variant_ids": [],
        "width": 123,
        "height": 456
      },
      "handle": "ipods_two",
      "image": null,
      "title": "IPods Two",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 691652237,
      "updated_at": "2020-02-06T12:33:39-05:00",
      "body_html": "<p>No ipods here</p>",
      "default_product_image": null,
      "handle": "non-ipods",
      "image": null,
      "title": "Non Ipods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    }
  ]
}
GET /admin/api/2020-04/collection_listings/#{collection_listing_id}/product_ids.json
Retrieve product_ids that are published to a collection_id. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

Amount of results

(default: 50, maximum: 1000)

Retrieve product_ids that are published to a collection_id

GET /admin/api/2020-04/collection_listings/#{collection_listing_id}/product_ids.json
View Response 
HTTP/1.1 200 OK
{
  "product_ids": [
    632910392
  ]
}
GET /admin/api/2020-04/collection_listings/#{collection_listing_id}.json
Retrieve a specific collection listing that is published to your app

Retrieve a specific collection listing that is published to your app

GET /admin/api/2020-04/collection_listings/#{collection_listing_id}.json
View Response 
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2020-02-06T12:33:39-05:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2020-02-06T12:33:39-05:00",
      "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-08-31T20:00:00-04:00"
  }
}
PUT /admin/api/2020-04/collection_listings/#{collection_listing_id}.json
Create a collection listing to publish a collection to your app

Create a collection listing to publish a collection to your app

PUT /admin/api/2020-04/collection_listings/#{collection_listing_id}.json
{
  "collection_listing": {
    "collection_id": 482865238
  }
}
View Response 
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2020-02-06T12:33:39-05:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2020-02-06T12:33:39-05:00",
      "src": "https://cdn.shopify.com/s/files/1/0006/9093/3842/collections/ipod_nano_8gb.jpg?v=1581010419"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-08-31T20:00:00-04:00"
  }
}
DELETE /admin/api/2020-04/collection_listings/#{collection_listing_id}.json
Delete a collection listing to unpublish a collection from your app

Delete a collection listing to unpublish a collection from your app

DELETE /admin/api/2020-04/collection_listings/#{collection_listing_id}.json
View Response 
HTTP/1.1 200 OK