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'

CollectionListing

Multiple access scopes needed — refer to each endpoint for access scope requirements.

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.

Only sales channels can publish collections using the REST Admin API. You can't publish collections and make them available to non-sales channels apps using the REST Admin API.

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.

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

The CollectionListing resource

Properties
collection_id
read-only
->id
Identifies which collection this listing is for.
body_html
read-only
->descriptionHtml
The description of the collection, complete with HTML formatting.
default_product_image
read-only
->featuredImage
The default product image for a collection.
image
read-only
->image
The image for a collection.
handle
read-only
->handle
A human-friendly unique string for the Collection automatically generated from its title.
published_at
read-only
->publishDate
The date and time when the collection was published. The API returns this in ISO_8601.
title
read-only
->title
The name of the collection.
sort_order
read-only
->sortOrder

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

updated_at
read-only
->updatedAt
The date and time when the collection was last modified. The API returns this in ISO_8601.
Was this section helpful?
{}The CollectionListing resource
{
  "collection_id": {
    "collection_id": 1053727709
  },
  "body_html": "It's a collection of curated products for the home page.",
  "default_product_image": [
    {
      "src": "http://example.com/burton.jpg"
    }
  ],
  "image": [
    {
      "src": "http://example.com/burton.jpg"
    }
  ],
  "handle": "ipod-nano",
  "published_at": "2007-12-31T19:00:00-05:00",
  "title": "Home page",
  "sort_order": "alpha-asc",
  "updated_at": "2012-08-24T14:01:47-04:00"
}
Anchor to section titled 'GET request, Retrieve collection listings that are published to your app'

get
Retrieve collection listings that are published to your app

collections
Requires product_listings access scope.
Retrieve collection listings that are published to your app. 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 Retrieve collection listings that are published to your app'

Parameters

api_version
string
required
limit
≤ 1000
default 50
Amount of results
Was this section helpful?
Anchor to section titled 'Examples of Retrieve collection listings that are published to your app'

Examples

Was this section helpful?
get
/admin/api/2024-07/collection_listings.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-07/collection_listings.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "collection_listings": [
    {
      "collection_id": 482865238,
      "updated_at": "2024-09-19T10:10:57-04:00",
      "body_html": "<p>The best selling ipod ever</p>",
      "default_product_image": null,
      "handle": "smart-ipods",
      "image": {
        "created_at": "2024-09-19T10:10:57-04:00",
        "src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/collections/ipod_nano_8gb.jpg?v=1726755057"
      },
      "title": "Smart iPods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 841564295,
      "updated_at": "2024-09-19T10:10:57-04:00",
      "body_html": "<p>The best selling ipod ever</p>",
      "default_product_image": null,
      "handle": "ipods",
      "image": {
        "created_at": "2024-09-19T10:10:57-04:00",
        "src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/collections/ipod_nano_8gb.jpg?v=1726755057"
      },
      "title": "IPods",
      "sort_order": "manual",
      "published_at": "2017-08-31T20:00:00-04:00"
    },
    {
      "collection_id": 395646240,
      "updated_at": "2024-09-19T10:10:57-04:00",
      "body_html": "<p>The best selling ipod ever. Again</p>",
      "default_product_image": {
        "id": 850703190,
        "created_at": "2024-09-19T10:10:57-04:00",
        "position": 1,
        "updated_at": "2024-09-19T10:10:57-04:00",
        "product_id": 632910392,
        "src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/products/ipod-nano.png?v=1726755057",
        "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": "2024-09-19T10:10:57-04: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"
    }
  ]
}
Anchor to section titled 'GET request, Retrieve a specific collection listing that is published to your app'

get
Retrieve a specific collection listing that is published to your app

collection
Requires product_listings access scope.
Retrieve a specific collection listing that is published to your app
Anchor to section titled 'Parameters of Retrieve a specific collection listing that is published to your app'

Parameters

api_version
string
required
collection_listing_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Retrieve a specific collection listing that is published to your app'

Examples

Path parameters
collectionlistingid=482865238
string
required
Was this section helpful?
get
/admin/api/2024-07/collection_listings/482865238.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-07/collection_listings/482865238.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2024-09-19T10:10:57-04:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2024-09-19T10:10:57-04:00",
      "src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/collections/ipod_nano_8gb.jpg?v=1726755057"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-08-31T20:00:00-04:00"
  }
}
Anchor to section titled 'GET request, Retrieve <code>product_ids</code> that are published to a <code>collection_id</code>'

get
Retrieve <code>product_ids</code> that are published to a <code>collection_id</code>

collection
Retrieve product_ids that are published to a collection_id. 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 Retrieve <code>product_ids</code> that are published to a <code>collection_id</code>'

Parameters

api_version
string
required
collection_listing_id
string
required
limit
≤ 1000
default 50
Amount of results
Was this section helpful?
Anchor to section titled 'Examples of Retrieve <code>product_ids</code> that are published to a <code>collection_id</code>'

Examples

Path parameters
collectionlistingid=841564295
string
required
Was this section helpful?
get
/admin/api/2024-07/collection_listings/841564295/product_ids.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-07/collection_listings/841564295/product_ids.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "product_ids": [
    632910392
  ]
}
Anchor to section titled 'PUT request, Create a collection listing to publish a collection to your app'

put
Create a collection listing to publish a collection to your app

collectionCreate
publishablePublish
Requires product_listings access scope.
Create a collection listing to publish a collection to your app
Anchor to section titled 'Parameters of Create a collection listing to publish a collection to your app'

Parameters

api_version
string
required
collection_listing_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Create a collection listing to publish a collection to your app'

Examples

Path parameters
collectionlistingid=482865238
string
required
Request body
collectionlisting
Collection_listing resource
Was this section helpful?
put
/admin/api/2024-07/collection_listings/482865238.json
Copy
curl -d '{"collection_listing":{"collection_id":482865238}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2024-07/collection_listings/482865238.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 200 OK
{
  "collection_listing": {
    "collection_id": 482865238,
    "updated_at": "2024-09-19T10:10:57-04:00",
    "body_html": "<p>The best selling ipod ever</p>",
    "default_product_image": null,
    "handle": "smart-ipods",
    "image": {
      "created_at": "2024-09-19T10:10:57-04:00",
      "src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/collections/ipod_nano_8gb.jpg?v=1726755057"
    },
    "title": "Smart iPods",
    "sort_order": "manual",
    "published_at": "2017-08-31T20:00:00-04:00"
  }
}
Anchor to section titled 'DELETE request, Delete a collection listing to unpublish a collection from your app'

del
Delete a collection listing to unpublish a collection from your app

publishableUnpublish
Requires product_listings access scope.
Delete a collection listing to unpublish a collection from your app
Anchor to section titled 'Parameters of Delete a collection listing to unpublish a collection from your app'

Parameters

api_version
string
required
collection_listing_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Delete a collection listing to unpublish a collection from your app'

Examples

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