Mastering Product & Collection Unpublishing in Shopify GraphQL: A Migration Guide

Migrating to Shopify's GraphQL Admin API from the REST API often presents new challenges, especially when familiar functions change. At Shopping Cart Mover, we frequently assist merchants in navigating these shifts.

The REST API's simple product.published = false no longer applies. As a community member, lkates, highlighted, the product.published field is absent in GraphQL. So, what's the new, authoritative method to "unpublish" products or collections? Let's explore the GraphQL approach, drawing insights from the Shopify Community and our expertise at Shopping Cart Mover.

The GraphQL Shift: Embracing 'Publications' for Granular Control

The biggest conceptual shift when moving to GraphQL for publishing and unpublishing is understanding 'publications'. Unlike the old binary "published or not published" status that applied broadly across all channels, GraphQL thinks in terms of specific sales channels. Your product isn't just "published"; it's published to your Online Store, or to your Buy Button channel, or to your Facebook Shop, and so on. This granular control is a powerful feature, especially for merchants managing multi-channel sales strategies.

This means that to unpublish something, you need to tell Shopify which specific publication (i.e., sales channel) you want to remove it from. This is where the publicationId becomes crucial.

Step-by-Step: Unpublishing Products and Collections with GraphQL

1. Finding Your Publication IDs

Before you can unpublish anything, you need to know the IDs of the sales channels you want to affect. This is often the easiest first step to see all your active sales channels and their corresponding IDs. You can run a simple GraphQL query to retrieve this information:

query GetPublicationIDs {
  publications(first: 10) {
    nodes {
      id
      name
    }
  }
}

This query will return a list of your sales channels, each with a unique id (e.g., gid://shopify/Publication/762454635) and a human-readable name (e.g., "Online Store"). You'll use these IDs in your unpublishing mutations.

2. The `publishableUnpublish` Mutation

Once you have the relevant publicationId, you can proceed with the unpublishing mutation. Shopify's GraphQL Admin API offers two primary mutations for this purpose, depending on your needs:

• productUnpublish: Specifically for unpublishing products.
• publishableUnpublish: A more versatile mutation that can unpublish both products and collections. For consistency and broader applicability, we often recommend publishableUnpublish.

Here's the mutation structure for publishableUnpublish, as shared by our community experts:

mutation PublishableUnpublish($id: ID!, $publicationId: ID!) {
  publishableUnpublish(id: $id, input: { publicationId: $publicationId }) {
    publishable {
      publishedOnPublication(publicationId: $publicationId)
    }
    userErrors {
      field
      message
    }
  }
}

And here's how you'd typically provide the variables:

{
  "id": "gid://shopify/Product/108828309",
  "publicationId": "gid://shopify/Publication/762454635"
}

In this example:

• id: This is the global ID of the product or collection you wish to unpublish.
• publicationId: This is the ID of the specific sales channel you obtained from the GetPublicationIDs query (e.g., your Online Store).

Important Note on Multiple Publications: To unpublish a product or collection from multiple sales channels, you generally need to call the publishableUnpublish mutation once for each publicationId. There isn't a single input array to unpublish from all channels simultaneously with this specific mutation, reinforcing the granular control aspect of GraphQL.

A Crucial Distinction: Unpublishing vs. Changing Product Status

This is where many migrating developers might get tripped up. It's vital to understand the difference between hiding a product from sales channels and changing its overall availability status within your Shopify admin.

• publishableUnpublish: Hiding from Sales Channels
  This mutation hides the product or collection from the specified sales channels (e.g., your online store, Facebook Shop). The product itself remains in your Shopify admin with its current status (e.g., "Active"). This is the direct equivalent of what product.published = false achieved in the REST API. The product is still "active" in your backend, just not visible to customers on specific storefronts.
• productUpdate with status: DRAFT or status: ARCHIVED: Changing Overall Product State
  If what you actually want is to take the product offline entirely, preventing it from being sold or even edited easily, you would use the productUpdate mutation to change its status.
  • Setting status: DRAFT will make the product a draft, typically hiding it from all sales channels and marking it as unfinished.
  • Setting status: ARCHIVED will archive the product, removing it from active listings and typically hiding it from all sales channels, often used for out-of-stock or discontinued items you wish to retain for historical data.

Choose based on your intent: do you want to hide from specific channels (publishableUnpublish) or change the product's overall administrative state (productUpdate)? For a direct migration from product.published = false, publishableUnpublish is the closest match.

Best Practices for GraphQL Migrations

• Test Thoroughly: Always test your GraphQL mutations in a development store or a staging environment before applying them to your live production store.
• Error Handling: Pay attention to the userErrors field in the mutation response. This provides valuable feedback if your mutation fails, helping you debug issues quickly.
• Batch Operations: If you need to unpublish a large number of products, consider implementing batch operations or queueing mechanisms to manage API rate limits and ensure efficient processing.
• Understand the Data Model: Invest time in understanding Shopify's GraphQL data model, especially concepts like 'publications', 'resources', and 'nodes'. This foundational knowledge will make future integrations much smoother.
• Stay Updated: The Shopify API is continuously evolving. Regularly check the Shopify Admin GraphQL API documentation for the latest mutations, queries, and best practices.

Conclusion

Shopify's GraphQL Admin API offers powerful, precise control, especially with its 'publications' concept. While the transition from REST's product.published = false requires adjustment, GraphQL provides granular control over product and collection visibility across sales channels. At Shopping Cart Mover, we specialize in seamless migrations, helping you leverage Shopify's full potential. For complex migrations or expert Shopify development, visit shoping-cart-mover.com. We're ready to help you confidently navigate the future of e-commerce!