CollectionListing

Sales Channel SDK

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

The collection_listings object represents the list of product collections that merchants have published to your channel. Each collection listing is represented by its collection_id. You can use this resource to retrieve collections for addition to your channel platform app. When used in conjunction with product listings, this enables customers to view product collections. You can also retrieve a list of product_ids published to a specific collection_id, or retrieve a specific collection_listing using its collection_id.

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
"collection_id": 1053727709

Identifies which collection this listing is for.

body_html
"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
"default_product_image": ["src": "http://example.com/burton.jpg"]

The default product image for a collection.

image
"image": ["src": "http://example.com/burton.jpg"]

The image for a collection.

handle
"handle": "ipod-nano"

A human-friendly unique string for the Collection automatically generated from its title.

published_at
"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
"title": "Home page"

The name of the collection.

sort_order
"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
"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/applications/1337/collection_listings.json
Retrieve collection listings that are published to a application_id
limit

Amount of results

(default: 50) (maximum: 250)
page

Page to show

(default: 1)

Retrieve collection listings that are published to a application_id

GET /admin/applications/#{id}/collection_listings.json
View Response
HTTP/1.1 200 OK
{
  "collection_listings": [
    {
      "collection_id": 482865238,
      "updated_at": "2017-01-31T13:13:42-05:00",
      "body_html": "<p>The best selling ipod ever<\/p>",
      "default_product_image": null,
      "handle": "smart-ipods",
      "image": {
        "created_at": "2017-01-31T13:13:30-05:00",
        "src": "https:\/\/cdn.shopify.com\/s\/files\/1\/0006\/9093\/3842\/collections\/ipod_nano_8gb.jpg?v=1485886410"
      },
      "title": "Smart iPods",
      "sort_order": "manual",
      "published_at": "2017-01-31T13:13:42-05:00"
    },
    {
      "collection_id": 691652237,
      "updated_at": "2017-01-31T13:13:42-05:00",
      "body_html": "<p>No ipods here<\/p>",
      "default_product_image": {
        "id": 850703190,
        "created_at": "2017-01-31T13:13:30-05:00",
        "position": 1,
        "updated_at": "2017-01-31T13:13:30-05:00",
        "product_id": 632910392,
        "src": "https:\/\/cdn.shopify.com\/s\/files\/1\/0006\/9093\/3842\/products\/ipod-nano.png?v=1485886410",
        "variant_ids": [
        ]
      },
      "handle": "non-ipods",
      "image": null,
      "title": "Non Ipods",
      "sort_order": "manual",
      "published_at": "2017-01-31T13:13:42-05:00"
    },
    {
      "collection_id": 395646240,
      "updated_at": "2017-01-31T13:13:41-05:00",
      "body_html": "<p>The best selling ipod ever. Again<\/p>",
      "default_product_image": {
        "id": 850703190,
        "created_at": "2017-01-31T13:13:30-05:00",
        "position": 1,
        "updated_at": "2017-01-31T13:13:30-05:00",
        "product_id": 632910392,
        "src": "https:\/\/cdn.shopify.com\/s\/files\/1\/0006\/9093\/3842\/products\/ipod-nano.png?v=1485886410",
        "variant_ids": [
        ]
      },
      "handle": "ipods_two",
      "image": null,
      "title": "IPods Two",
      "sort_order": "manual",
      "published_at": "2017-01-31T13:13:41-05:00"
    },
    {
      "collection_id": 841564295,
      "updated_at": "2017-01-31T13:13:41-05:00",
      "body_html": "<p>The best selling ipod ever<\/p>",
      "default_product_image": null,
      "handle": "ipods",
      "image": {
        "created_at": "2017-01-31T13:13:30-05:00",
        "src": "https:\/\/cdn.shopify.com\/s\/files\/1\/0006\/9093\/3842\/collections\/ipod_nano_8gb.jpg?v=1485886410"
      },
      "title": "IPods",
      "sort_order": "manual",
      "published_at": "2017-01-31T13:13:41-05:00"
    }
  ]
}
GET /admin/applications/1337/collection_listings/841564295/product_ids.json
Retrieve product_ids that are published to a collection_id

Retrieve product_ids that are published to a collection_id

GET /admin/applications/#{id}/collection_listings/#{id}/product_ids.json
View Response
HTTP/1.1 200 OK
{
  "product_ids": [
    632910392,
    632910392
  ]
}
GET /admin/applications/1337/collection_listings/482865238.json
Retrieve a specific collection listing that is published to a application_id

Retrieve a specific collection listing that is published to a application_id

GET /admin/applications/#{id}/collection_listings/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2017-01-31T13:13:45-05:00",
    "body_html": "<p>The best selling ipod ever<\/p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2017-01-31T13:13:30-05:00",
      "src": "https:\/\/cdn.shopify.com\/s\/files\/1\/0006\/9093\/3842\/collections\/ipod_nano_8gb.jpg?v=1485886410"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-01-31T13:13:45-05:00"
  }
}