Missing Metadata App Store Connect: gỡ kẹt gói đăng ký

Missing Metadata trong App Store Connect nghĩa là gói đăng ký hoặc giao dịch mua trong ứng dụng của bạn còn thiếu ít nhất một thông tin bắt buộc. Hãy kiểm tra lần lượt ngôn ngữ, giá, thời hạn, quốc gia, ảnh chụp xét duyệt và hợp đồng ứng dụng trả phí. Chừng nào sản phẩm còn ở trạng thái này, bạn không thể gửi nó đi xét duyệt, và ứng dụng của bạn cũng không tải được nó. Ngoài ra, gói đăng ký đầu tiên phải được gửi cùng một phiên bản ứng dụng.

Mình gặp trạng thái này vào tháng 7 năm 2026 trên TradaZen, ứng dụng mô phỏng giao dịch của mình. Gói đăng ký hằng tuần mới tạo đã có thời hạn, giá, nhóm và hai ngôn ngữ. Vậy mà nó vẫn nằm ở "Missing Metadata". Thứ duy nhất còn thiếu là ảnh chụp xét duyệt. Dưới đây là các nguyên nhân cần kiểm tra, các trạng thái của một sản phẩm kèm cách gỡ từng trạng thái, rồi đến mối liên hệ với RevenueCat.

Missing Metadata nghĩa là gì?

Cho đến năm nay, trang trợ giúp của Apple định nghĩa trạng thái này như sau: sản phẩm đã được tạo, nhưng bạn chưa gửi ảnh chụp màn hình hoặc chưa hoàn tất metadata của nó. Trạng thái này không bao giờ cho biết trường nào bị thiếu. Vấn đề nằm ở đó: bạn phải tự đi tìm.

Lưu ý, nhãn này đã thay đổi vào tháng 7 năm 2026. Ghi chú phát hành của App Store Connect thông báo vào ngày 15 tháng 7 một cách gửi mới: mỗi giao dịch mua trong ứng dụng được gửi từ trang riêng của nó, bằng Add for Review. Trang các trạng thái không còn liệt kê "Missing Metadata" nữa. Nó bắt đầu bằng "Prepare for Submission" và nói rõ: nếu giao dịch mua trong ứng dụng của bạn thiếu metadata bắt buộc, hãy điền đủ trước khi thêm nó vào một lần gửi. Tài liệu của RevenueCat cũng xác nhận: trước khi xét duyệt, một sản phẩm mới hiển thị là "Prepare for Submission", kể cả khi nó còn thiếu metadata.

Còn API App Store Connect thì vẫn trả về MISSING_METADATA rồi READY_TO_SUBMIT. Vì vậy các công cụ dựa trên API này vẫn hiển thị những từ đó. Dù nhãn là gì, chẩn đoán vẫn như nhau: có một trường bắt buộc đang trống.

Các nguyên nhân cần kiểm tra, theo thứ tự

Mình kiểm tra theo thứ tự này, từ trang sản phẩm đến tài khoản.

Nguyên nhân	Sửa ở đâu
Tên hoặc mô tả trống	Trang sản phẩm
Nhóm không có tên hiển thị	Trang nhóm
Thiếu giá hoặc thời hạn	Trang sản phẩm
Không có quốc gia nào khả dụng	Availability
Thiếu ảnh chụp xét duyệt	Review Information
Hợp đồng trả phí chưa kích hoạt	Business
Gói đăng ký đầu tiên gửi riêng lẻ	Lần gửi

1. Ngôn ngữ của sản phẩm. Theo trang thông tin của một giao dịch mua trong ứng dụng, tên hiển thị và mô tả là bắt buộc ở ít nhất một ngôn ngữ. Tên dài từ 2 đến 30 ký tự, mô tả tối đa 45 ký tự. Một sản phẩm không có ngôn ngữ nào thì không thể gửi đi.

2. Ngôn ngữ của nhóm. Nhóm đăng ký cũng có tên hiển thị, thứ người đăng ký nhìn thấy khi quản lý gói đăng ký trên iPhone. Bạn thêm nó trên trang của nhóm, mục Display Name and Description, như trang của Apple về gói đăng ký giải thích. Trường này trông có vẻ không bắt buộc. Thế nhưng một lập trình viên kể trên diễn đàn của Apple rằng mọi gói đăng ký trong nhóm của anh ấy đều bị kẹt chừng nào trường đó còn trống. Trạng thái hiển thị trên gói đăng ký chứ không phải trên nhóm, nên mới dễ nhầm.

3. Giá và thời hạn. Một gói đăng ký cần có thời hạn, từ một tuần đến một năm, và một mức giá. Ghi chú kỹ thuật TN3186 bắt đầu từ đây khi một sản phẩm không tải được: kiểm tra mã định danh, giá và ngôn ngữ của nó. Bạn cũng nhớ rằng thời hạn không thể sửa sau khi đã gửi đi xét duyệt.

4. Tính khả dụng. Hãy chọn ít nhất một quốc gia hoặc khu vực trong Availability. Apple nói rõ: nếu không có tính khả dụng, trạng thái "Approved" không thể xuất hiện.

5. Ảnh chụp xét duyệt. Đây là trường hợp của mình trên TradaZen, và là nguyên nhân hay gặp trên các diễn đàn. Ảnh "App Review Screenshot" cho thấy giao dịch mua như nó xuất hiện trong ứng dụng, thường là paywall của bạn. Ảnh này chỉ dành cho người xét duyệt và không bao giờ hiển thị trên App Store. Nó theo đúng kích thước của ảnh chụp App Store. Khi đã gửi, bạn có thể thay nó, nhưng không xóa được.

Đừng nhầm nó với ảnh quảng bá 1024 x 1024 pixel. Ảnh đó chỉ cần khi bạn muốn làm nổi bật giao dịch mua trên trang ứng dụng hoặc khi tạo một ưu đãi thu hút người dùng quay lại, và nó có quy định riêng. Mình đã học được điều này qua một lần bị từ chối vì ảnh quảng bá của một gói đăng ký.

6. Hợp đồng ứng dụng trả phí. Để bán giao dịch mua trong ứng dụng, chủ tài khoản phải ký Paid Apps Agreement trong Business, rồi điền thông tin ngân hàng và thuế. Đây không phải một trường của sản phẩm, nhưng mọi thứ đều phụ thuộc vào nó. Apple viết rằng bạn không thể tạo giao dịch mua trong ứng dụng mới chừng nào chưa chấp nhận phiên bản hợp đồng mới nhất. Trang của Apple về chuẩn bị giao dịch mua để xét duyệt còn nói thêm rằng giao dịch mua trả phí không hoạt động trong quá trình xét duyệt chừng nào hợp đồng này chưa kích hoạt. Trong Business, hợp đồng, tài khoản ngân hàng và các biểu mẫu thuế đều phải ở trạng thái hoạt động. Các bước này được trình bày chi tiết trong hướng dẫn về tài khoản nhà phát triển Apple.

7. Gói đăng ký đầu tiên được gửi riêng lẻ. Đây không phải là thiếu metadata. Nhưng đây lại là lý do phổ biến nhất khiến một sản phẩm đầy đủ thông tin mãi không được gửi đi xét duyệt. Mình giải thích chi tiết ở bên dưới.

Các trạng thái của một sản phẩm và cách gỡ từng trạng thái

Đây là danh sách kiểm tra mình luôn để trước mắt. Cột đầu tiên là trạng thái API trả về, cột thứ hai là nhãn trong trang trợ giúp của Apple từ tháng 7 năm 2026.

Trạng thái (API)	Nhãn hiện tại	Cách gỡ
MISSING_METADATA	Prepare for Submission	Điền các trường
READY_TO_SUBMIT	Prepare for Submission	Add for Review
Không có tương ứng	Ready for Review	Submit for Review
WAITING_FOR_REVIEW	Waiting for Review	Chờ Apple
IN_REVIEW	In Review	Chờ Apple
APPROVED	Approved	Có quốc gia và app đã duyệt
REJECTED	Rejected	Sửa, Update Review

Chi tiết:

• Từ Missing Metadata sang Ready to Submit. Điền các trường của nguyên nhân 1 đến 5, lưu lại, tải lại trang. Màn hình mình thấy hồi tháng 7 hiển thị "Missing Metadata", và trạng thái tiếp theo là "Ready to Submit".
• Từ Ready to Submit sang Ready for Review. Trên trang của gói đăng ký, bấm Add for Review và thêm nó vào một lần gửi có sẵn hoặc một lần gửi mới. Quy trình gửi một giao dịch mua trong ứng dụng sẽ yêu cầu bạn chọn nền tảng, phiên bản ứng dụng và, nếu cần, nhóm. Từ lúc này, chỉ còn tên tham chiếu, giá và tính khả dụng là sửa được.
• Từ Ready for Review sang Waiting for Review. Kiểm tra rằng phiên bản ứng dụng và nhóm nằm trong cùng một lần gửi, rồi bấm Submit for Review.
• Từ Waiting for Review sang Approved. Không cần làm gì, chỉ cần giữ paywall của bạn hoạt động bình thường. Nếu giao dịch mua chuyển sang "Accepted" chứ không phải "Approved", nghĩa là một thành phần khác trong cùng lần gửi đã bị từ chối: Apple không duyệt gì cả chừng nào mọi thứ chưa được chấp nhận.
• Rejected. Lý do hiển thị trong tin nhắn của lần gửi. Sửa thành phần đó, bấm Update Review, rồi gửi lại.

Gói đăng ký đầu tiên phải đi cùng một phiên bản ứng dụng

Quy tắc này nằm trong trang trợ giúp của Apple: gói đăng ký đầu tiên, cũng như giao dịch mua đầu tiên của mỗi loại, phải được gửi cùng một phiên bản ứng dụng mới. Một nhóm mới được gửi kèm ít nhất một gói đăng ký của nó. Khi thành phần đầu tiên này đã được duyệt, bạn có thể gửi các thành phần tiếp theo cùng loại mà không cần phiên bản mới, miễn là ứng dụng có một phiên bản đã được duyệt.

Đó chính là chuyện đã xảy ra với TradaZen. Phiên bản tháng 7 được gửi cùng gói năm và gói tháng. Gói tuần, khi đó vẫn ở "Missing Metadata", nằm ngoài lần gửi. Khi ứng dụng đã được duyệt, gói này có thể gửi riêng, không cần build mới.

Nếu bạn gửi ứng dụng mà không kèm gói đăng ký, bạn sẽ cần một phiên bản mới để được duyệt gói đó. Hướng dẫn về thời gian duyệt App Store cho thấy thêm một vòng như vậy tốn bao nhiêu ngày.

Mối liên hệ với RevenueCat: offering trống

RevenueCat không tự bán gì cả. SDK đọc mã định danh sản phẩm của bạn trên máy chủ của RevenueCat, rồi yêu cầu sản phẩm từ App Store, ngay trên iPhone. Nếu App Store không trả về, offering sẽ trống và paywall của bạn không có gì để hiển thị. Khi đó log của SDK hiện: "There's a problem with your configuration. None of the products registered in the RevenueCat dashboard could be fetched from the App Store."

Theo RevenueCat, một sản phẩm có metadata đầy đủ sẽ tải được trong sandbox ngay cả trước khi xét duyệt. Sản phẩm thiếu thông tin thì không. Các hướng khác mà RevenueCat và Apple đưa ra:

• hợp đồng ứng dụng trả phí và thông tin ngân hàng, có thể mất tới 24 giờ để có hiệu lực theo RevenueCat;
• một thay đổi trên sản phẩm, có thể mất tới một giờ để xuất hiện trong sandbox theo Apple;
• mã định danh sản phẩm khác nhau giữa App Store Connect, RevenueCat và code của bạn.

Trên TradaZen, code sẽ ẩn thẻ của gói đăng ký nào mà sản phẩm không được trả về, mà không làm hỏng paywall. Vào tháng 10 năm 2026, mình gặp một paywall không có offering vì lý do khác: offering đọc từ cache của SDK bị trống. Từ đó, nếu offering trống, code của ứng dụng sẽ yêu cầu sản phẩm trực tiếp từ StoreKit, và đề nghị thử lại nếu store không phản hồi.

Một paywall không có offering không bao giờ được là ngõ cụt, với người dùng cũng như với người xét duyệt, người phải mua được. Cách thiết lập đầy đủ có trong hướng dẫn RevenueCat cho gói đăng ký iOS của mình, còn các bẫy hiển thị nằm trong các lỗi paywall. Khi sản phẩm đã sẵn sàng, hãy kiểm tra thêm rằng paywall của bạn tuân thủ guideline 3.1.2.

Kết nối gói đăng ký mà không mất cả tuần

iOS & Android Kit xuất phát từ Starter Code của các ứng dụng của mình: onboarding, paywall và gói đăng ký đã được code sẵn, và bước thứ ba, "kết nối dòng tiền", hướng dẫn bạn thiết lập chúng. Toàn bộ chuỗi, từ sản phẩm trong App Store Connect đến xác minh giao dịch mua, được mô tả trên trang gói đăng ký trong ứng dụng iOS.

Nếu bạn đang chuẩn bị phát hành lần đầu, làm bài chẩn đoán miễn phí: nó sắp xếp lại các bước theo thứ tự và gửi bạn checklist chống bị Apple từ chối của mình. Nếu gói đăng ký của bạn vẫn kẹt dù đã làm hết những điều trên, đặt một giờ với mình: chúng ta cùng mở App Store Connect của bạn và tìm trường còn trống.

Câu hỏi thường gặp

Vì sao gói đăng ký của tôi vẫn ở Missing Metadata dù đã điền đủ hết?

Trước tiên hãy kiểm tra ảnh chụp xét duyệt, rồi đến tên hiển thị của nhóm đăng ký, trường trông có vẻ không bắt buộc. Sau đó kiểm tra giá, thời hạn, ít nhất một quốc gia và hợp đồng ứng dụng trả phí trong Business. Sau mỗi lần sửa, hãy lưu và tải lại trang trước khi kết luận.

Gói đăng ký có cần ảnh chụp màn hình không?

Có, đó là ảnh chụp xét duyệt, gọi là App Review Screenshot. Ảnh này cho thấy giao dịch mua trong ứng dụng, thường là paywall, và chỉ dành cho người xét duyệt. Nó không hiển thị trên App Store. Đừng nhầm với ảnh quảng bá 1024 x 1024 pixel, chỉ cần khi muốn làm nổi bật giao dịch mua hoặc cho một ưu đãi thu hút người dùng quay lại.

Có thể gửi gói đăng ký mà không cần phiên bản ứng dụng mới không?

Gói đầu tiên thì không. Gói đăng ký đầu tiên và nhóm của nó phải đi cùng một phiên bản ứng dụng mới. Khi gói đầu tiên đã được duyệt, các gói tiếp theo có thể gửi riêng, miễn là ứng dụng có một phiên bản đã được duyệt.

Prepare for Submission nghĩa là gì với một giao dịch mua trong ứng dụng?

Đó là nhãn trong trang trợ giúp của Apple từ tháng 7 năm 2026 cho một sản phẩm chưa được thêm vào lần gửi nào. Nhãn này hiển thị ngay cả khi còn thiếu metadata. API App Store Connect vẫn phân biệt hai trường hợp, với MISSING_METADATA và READY_TO_SUBMIT.

Vì sao RevenueCat trả về offering trống?

Vì App Store không trả về sản phẩm nào cho iPhone. Các nguyên nhân phổ biến nhất: metadata chưa đầy đủ, hợp đồng ứng dụng trả phí chưa kích hoạt, mã định danh sản phẩm không khớp, hoặc thay đổi gần đây chưa có hiệu lực. Paywall của bạn phải xử lý được trường hợp này mà không chặn người dùng.