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.

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

Properties

collection_id
read-only
->id
Identifies which collection this listing is for.

body_html
read-only
The description of the collection, complete with HTML formatting.

default_product_image
read-only
The default product image for a collection.

image
read-only
The image for a collection.

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

published_at
read-only
The date and time when the collection was published. The API returns this in ISO_8601.

title
read-only
The name of the collection.

sort_order
read-only

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


updated_at
read-only
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"
}

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.

api_version
string
required

limit
≤ 1000
default 50
Amount of results

Was this section helpful?
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"
    }
  ]
}

Requires product_listings access scope.

Retrieve a specific collection listing that is published to your app

api_version
string
required

collection_listing_id
string
required

Was this section helpful?
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>

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.

api_version
string
required

collection_listing_id
string
required

limit
≤ 1000
default 50
Amount of results

Was this section helpful?
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
  ]
}

Requires product_listings access scope.

Create a collection listing to publish a collection to your app

api_version
string
required

collection_listing_id
string
required

Was this section helpful?
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"
  }
}

Requires product_listings access scope.

Delete a collection listing to unpublish a collection from your app

api_version
string
required

collection_listing_id
string
required

Was this section helpful?
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