Are the GraphQL API doc regarding updating/creating collections outdated?

Retired Boards Appdev Graphql Basics And Troubleshooting

Topic summary

Documentation for Shopify Admin GraphQL mutations around collections appears inconsistent with actual behavior.

  • Reported issue: Docs for collectionCreate and collectionUpdate state the id field “specifies the collection to update or create a new collection if absent,” implying an upsert-like behavior.
  • Observed behavior: collectionCreate returns an error when id is provided (“id cannot be specified on collection creation”). collectionUpdate returns an error if id is missing (“id must be specified on collectionUpdate”).
  • Implication: The API enforces distinct operations—creation without an id and updates requiring an id—contradicting the documented “create if absent” wording.
  • Evidence: A test input including an id on collectionCreate produced the error; omitting id on collectionUpdate produced the opposite error.
  • Action taken: Another participant replicated the results and escalated the issue to the developer documentation team for clarification/enhancement.
  • Status: Unresolved. Awaiting documentation update; no API changes or official clarification provided yet.
Summarized with AI on February 11. AI used: gpt-5.
1

I believe the API docs are out of date for updating on collection creation and creating on collection update.

On collectionCreate under id it states:

Specifies the collection to update or create a new collection if absent.

With this input:

  input: {
    title: 'Special Snares',
    descriptionHtml: 'Test',
    id: 'gid://shopify/Collection/299687116949'
  }

I receive this response:

"userErrors":[{"field":["id"],"message":"id cannot be specified on collection creation","__typename":"UserError"}]

And on the other end, with collectionUpdate, it states:

Specifies the collection to update or create a new collection if absent.

And I receive this response with an id attached:

id must be specified on collectionUpdate
2

Hi @brydom ,

Thanks for your post and for sharing your findings!

I tested this on my end as well with the same results and I have sent this to our developer documents team to clarify / enhance.

Thanks again for taking the time to report it.

1 Like