Shopify đổi Collections API 2026: collection biến mất

Một smart collection tự dưng mất khỏi app bên thứ ba. Shopify đổi Collections API 2026 lọc bỏ collection model mới khỏi các phiên bản API cũ.

Linh Nguyen · Cập nhật 2026-07-18

Dấu hiệu đầu tiên không phải là một thông báo lỗi. Chính vì thế mà tôi mất hai ngày mới lần ra.

Đầu tháng 7/2026, một trong những store chúng tôi giúp vận hành có một smart collection chạy theo tag — loại tự động gom mọi sản phẩm được gắn tag cho một đợt đẩy hàng theo mùa. Trong Shopify admin nó hiện đầy đủ. Ngoài storefront merchandising cũng đúng. Nhưng trong cái app bên thứ ba chúng tôi dùng để rà soát rule của collection trên cả fleet, collection đó đơn giản là không có trong danh sách. Không hỏng. Không bị đánh cờ cảnh báo. Chỉ vắng mặt, như thể nó chưa từng tồn tại.

Nếu nó văng ra một 404 hay một lỗi permission, chắc tôi tìm ra trong một tiếng. Biến mất trong im lặng là kiểu lỗi tệ nhất, vì chẳng có gì bảo bạn phải đi tìm. Chủ store chỉ để ý ra khi một bản export định kỳ đổ vào Google Sheet trả về thiếu đúng một collection, mà ngay cả lúc đó thì giả định đầu tiên — của cả tôi nữa — là có ai đó đã xoá nó.

Đuổi nhầm thủ phạm trước đã

Hai giả thuyết đầu tiên của tôi đều sai, và cả hai đều ngốn thời gian.

Giả thuyết một: ai đó xoá hoặc unpublish nó. Loại nhanh — collection vẫn live, đã publish ra kênh Online Store, và số lượng sản phẩm trong admin vẫn đúng. Dù chuyện gì đang xảy ra thì collection vẫn tồn tại và vẫn chạy; nó chỉ vô hình với đúng một tool.

Giả thuyết hai: vấn đề permission hoặc API scope của app. Đây là nghi phạm quen thuộc mỗi khi một tool bên thứ ba không thấy được thứ gì đó. Tôi kiểm tra lại scope của app, cài lại nó lên một store test, ngồi xem cả luồng OAuth grant. App có read_products và quyền truy cập collection. Nó thấy được mọi collection khác trên store. Chỉ mỗi cái này — và, khi tôi bắt đầu dò kỹ, thêm vài collection mới hơn trên cùng store đó — là nhất quyết không chịu hiện ra.

Chính chi tiết đó cuối cùng chỉ tôi đi đúng hướng. Không phải store. Không phải permission của app. Mà là một điều gì đó riêng biệt ở chính những collection này. Và điểm chung của chúng là chúng vừa được dựng lại gần đây, bằng trình chỉnh sửa rule collection mới.

Cái thay đổi tôi chưa đọc kỹ: Collection.sources

Mấy tuần trước tôi có lướt qua mục changelog của Shopify rồi xếp nó vào ngăn "để sau đọc cho tử tế." "Sau" đã tới. Mục đó — New Collection model and APIs now available — mô tả một thay đổi thực sự về mặt cấu trúc trong cách collection được biểu diễn, chứ không phải một chỉnh sửa API cho có.

Đây là hình dạng của nó, đã đối chiếu với chính tài liệu của Shopify. Bắt đầu từ GraphQL Admin API phiên bản 2026-07, hiệu lực từ ngày 1/7/2026, một collection không còn được định nghĩa bằng một rule set duy nhất nữa. Field cũ Collection.ruleSet — cái mà mọi tool smart-collection đã đọc suốt bao năm — bị deprecated, thay bằng Collection.sources. Thay vì một ruleSet mô tả "các sản phẩm có tag bằng X," giờ một collection mang một hoặc nhiều object CollectionSource, mỗi cái thêm sản phẩm hoặc variant qua điều kiện có kiểu (typed condition) hoặc chọn thủ công. Đây là một model biểu đạt được nhiều hơn, và với kiểu merchandising đa nguồn mà các catalog lớn hơn cần, rõ ràng nó tốt hơn.

Phần liên quan tới màn biến mất là hành vi tương thích ngược, và tôi trích nguyên văn Shopify vì không muốn diễn đạt sai. Theo changelog: "In earlier API versions, those same collections using new features are filtered out because the legacy ruleSet shape can't represent them." (Ở các phiên bản API cũ hơn, chính những collection dùng tính năng mới đó bị lọc bỏ, vì hình dạng ruleSet cũ không thể biểu diễn chúng.) Và cách khắc phục Shopify nêu ra cũng thẳng thừng không kém: "Migrate to the 2026-07 API version to see and manage all collections in a shop." (Hãy chuyển sang phiên bản API 2026-07 để thấy và quản lý toàn bộ collection trong một shop.)

Đọc lại hai lần đi, vì đó là toàn bộ câu chuyện. Một collection dựng trên model mới không bị trả về dưới dạng lỗi cho client dùng phiên bản cũ. Nó cũng không bị trả về dưới dạng object thiếu một phần. Nó bị lọc bỏ — biến mất hoàn toàn khỏi response — vì hình dạng ruleSet cũ không có cách nào biểu diễn nó. Một app bị ghim ở 2026-04 hoặc cũ hơn khi hỏi danh sách collection của bạn sẽ nhận một danh sách âm thầm loại đi những cái theo model mới. Không 4xx. Không cảnh báo. Chỉ là một danh sách ngắn hơn.

Đó đúng là cái lỗi tôi đã trân trối nhìn suốt hai ngày. Chủ store đã dựng lại vài collection bằng trình editor mới, tức là đưa chúng lên model mới. App rà soát của chúng tôi thì vẫn đọc trên một phiên bản API cũ hơn. Đứng từ góc nhìn của app, những collection đó thực sự không tồn tại.

Vì sao đây là vấn đề của cả fleet, không phải bug một store

Nếu bạn chỉ chạy một store, chuyện này đọc như một điều lạ bạn gặp một lần rồi fix xong. Trên cả fleet thì nó khó chịu hơn nhiều, vì lỗi xuất hiện không đều.

Chỉ những collection dùng model mới mới bị lọc bỏ. Một store mà không ai từng đụng vào trình editor collection mới thì vẫn chạy hoàn hảo trên các tool phiên bản cũ — mọi collection vẫn có hình dạng tương thích với model cũ. Nên trên một fleet, giả sử một tá store, cái app quản lý collection của bạn nhìn hoàn toàn khỏe mạnh ở mười một store, rồi âm thầm bỏ rơi collection ở đúng cái store mà có người đã thử nghiệm trình dựng rule mới. Nhìn dashboard bạn sẽ không nhận ra. Store nào cũng báo "collections: OK." Khoảng trống chỉ lộ ra khi một collection cụ thể bạn định thao tác lại không có mặt — và nếu quy trình của bạn là "chọn hết collection, apply thay đổi," thì những cái bị thiếu cứ lặng lẽ không được áp thay đổi.

Đây đúng cùng một lớp vấn đề với thứ tôi từng viết trong bài về rate limit API trên nhiều store: bug nằm ở khe giữa các giả định của bộ tool và trạng thái thật của từng store, và nó ẩn cho tới khi một store trôi ra khỏi khoảng mà tool được dựng cho. Version drift là người anh em trầm lặng của rate-limit drift.

Câu hỏi duy nhất giờ tôi đặt cho mọi vendor có tool đụng tới collection theo lô: đã chuyển từ ruleSet sang Collection.sources ở API phiên bản 2026-07 chưa? Nếu câu trả lời là chưa, hoặc "đang làm," thì bạn biết chính xác store nào của mình đang rủi ro — những store đang dùng collection model mới — và bạn có thể tạm hoãn việc chỉnh sửa model mới ở đó cho tới khi tool bắt kịp. Shopify hỗ trợ mỗi phiên bản API ổn định tối thiểu 12 tháng, với ít nhất chín tháng gối đầu giữa hai phiên bản liền kề, nên một app chưa migrate thì không báo lỗi; nó chỉ đơn giản là mù trước hình dạng mới. Điều đó còn tệ hơn báo lỗi, và đó là lý do bạn phải chủ động hỏi thay vì ngồi chờ một cú crash.

Sau vụ này tôi thực sự đổi những gì

Hai thứ, chẳng có gì hào nhoáng.

Thứ nhất, tôi thôi tin vào sự im lặng của một tool. Với bất cứ thứ gì đọc collection theo lô — cái app rà soát, bản export nuôi quy trình quản lý tag và theme hàng loạt, các job xử lý sản phẩm và catalog bằng CSV — giờ tôi đều kiểm tra nó ghim ở phiên bản API nào trước khi tin rằng "không có kết quả" nghĩa là "chẳng có gì ở đó." Đối chiếu số lượng giúp ích: admin báo store có 47 collection, tool trả về 44, thì khoảng lệch ba collection đó chính là chuông báo mà hồi tháng 7 tôi đã không có.

Thứ hai, tôi trở nên chủ đích về việc tool nào được phép đụng tới collection model mới. Cho tới khi một vendor xác nhận hỗ trợ 2026-07, collection model mới trên một store chỉ được chỉnh trong Shopify admin, không qua app bên thứ ba — vì một app còn không thấy được collection thì chắc chắn không thể bulk-edit an toàn quanh nó. Đây cũng chính là lối lập luận đẩy tôi liên tục đánh giá lại các app đa store bên thứ ba so với thứ mình tự sở hữu được: mỗi dependency bạn không kiểm soát là một lịch trình version-migration bạn cũng không kiểm soát.

Còn đây là quan điểm thật của tôi, và nó không nằm ở thiết kế API. Collection.sources là một model tốt hơn; tôi mừng vì nó ra đời. Điều tôi phàn nàn là kiểu lỗi. "Lọc bỏ" là một lựa chọn kỹ thuật có lý — bạn không thể nhét một hình dạng mới vào một hợp đồng cũ — nhưng bỏ đi trong im lặng đồng nghĩa cái giá rơi xuống đầu người ở phía cuối chuỗi và ít có khả năng chẩn đoán nhất, mà trên một fleet thì đó là người vận hành đang trân trối nhìn một cái Sheet thiếu đúng một dòng. Nếu tôi được thiết kế, tôi sẽ muốn client phiên bản cũ nhận một tín hiệu rõ ràng, bắt được, rằng có collection model mới tồn tại nhưng không thể biểu diễn — chứ không phải một danh sách ngắn hơn nhìn cứ như đã đầy đủ.

Ở StoreFleet chúng tôi không làm tool quản lý rule của collection — inventory sync, cảnh báo, và theo dõi đơn hàng lẫn vận đơn mới là thứ chúng tôi tự làm chủ trọn vẹn. Nhưng chính vụ này là lý do tôi bận tâm tới việc mọi thứ trong stack đọc trên phiên bản API nào. Một tool âm thầm im lặng thay vì kêu to sẽ ngốn của bạn cả một store đáng giá về niềm tin trước khi bạn kịp nhận ra, và cách phòng thủ duy nhất là biết trước version drift đang tới, trước khi nó chạm tới đúng cái store nơi nó thực sự cắn.