Để người dùng cam kết thanh toán theo năm nhưng trả tiền hàng tháng, hãy thêm gói cam kết 12 tháng vào sản phẩm hàng năm của bạn trong App Store Connect và trong Adapty.

Trước khi bắt đầu

Trước khi triển khai commitment plans, hãy đảm bảo rằng bạn:

• Nhắm đúng thị trường: Commitment plan không khả dụng ở Hoa Kỳ. Ở Đức, Israel, Nam Phi và Türkiye, người dùng có thể hủy ngay lập tức thông qua Apple Support.
• Nhắm đúng phiên bản hệ điều hành: Người dùng cần iOS 26.4 trở lên, hoặc cùng phiên bản đó của iPadOS, macOS, tvOS, hay visionOS. Build app với Xcode 26.5 trở lên.
• Nhắm đúng khoảng giá: Tổng giá trị của 12 lần thanh toán hàng tháng phải nằm trong khoảng từ 1x đến 1.5x so với giá trị của gói đăng ký năm trả trước.
• Chạy Adapty SDK v4.3 trở lên: Trong các phiên bản app dùng SDK cũ hơn, người dùng chỉ có thể mua gói trả trước.
• Cập nhật code xử lý product ID: Webhook, tích hợp, xuất dữ liệu và Server-side API báo cáo các giao dịch mua commitment plan dưới dạng <product_id>:monthly. Nếu code của bạn xử lý product ID, hãy cập nhật logic trước khi có giao dịch commitment plan đầu tiên.

Cấu hình App Store Connect

1. Mở một gói đăng ký hàng năm trong App Store Connect, hoặc tạo gói đăng ký mới với thời hạn 1 Year.
2. Trong phần Availability, thêm các quốc gia tương tự vào mục 1 Year Upfront và Monthly with 12-Month Commitment. Apple chỉ cung cấp hình thức thanh toán cam kết ở những nơi có hình thức thanh toán trả trước. Chiều ngược lại không bắt buộc: bạn có thể cung cấp gói trả trước ở các quốc gia không có gói cam kết.
3. Trong phần Subscription Prices, đặt giá trả trước cho vùng lãnh thổ cơ sở của bạn, nếu gói đăng ký chưa có. Apple yêu cầu giá trả trước ngay cả khi bạn chỉ hiển thị gói cam kết cho người dùng.
4. Đặt giá hàng tháng cho vùng lãnh thổ cơ sở của bạn. Giá hàng tháng phải bằng 1/12 đến 1/8 giá trả trước. Ví dụ: với giá trả trước €59.99, giá hàng tháng có thể là €5.00 đến €7.49.

App Store Connect tính giá cho các quốc gia khác dựa trên giá của lãnh thổ gốc của bạn.

Để biết hướng dẫn đầy đủ, hãy xem hướng dẫn của Apple về cách cung cấp gói đăng ký hàng tháng với cam kết 12 tháng.

2. Cấu hình Adapty

Để hiển thị commitment plan trong các paywall tùy chỉnh, hãy bật tính năng này cho sản phẩm theo năm trong Adapty. Nếu bạn không dùng custom paywall, bạn có thể bỏ qua bước này.

1. Mở sản phẩm theo năm. Nếu sản phẩm chưa tồn tại, hãy tạo và kết nối gói đăng ký bạn đã thiết lập trong App Store Connect. Đừng tạo sản phẩm mới từ Adapty vì sẽ tạo ra một gói đăng ký riêng biệt không có commitment plan.

2. Mở tab App Store, rồi chọn Offer monthly payments with a 12-month commitment.

   

3. Trong cửa sổ bật lên, từ danh sách Monthly price, USD, chọn mức giá trả góp khớp với App Store Connect. Danh sách chỉ chứa các mức giá App Store trong phạm vi cho phép. Giá này là giá trị tham chiếu: Adapty không gửi nó đến App Store Connect.

   

3. Thiết lập ưu đãi

Trong App Store Connect, mỗi gói thanh toán có các ưu đãi giới thiệu, ưu đãi, ưu đãi thu hút khách hàng cũ, và mã ưu đãi riêng. Ưu đãi cho gói trả trước không áp dụng cho gói cam kết.

• Dùng thử miễn phí và các ưu đãi giới thiệu khác: Trong App Store Connect, thiết lập ưu đãi cho gói cam kết. Adapty sẽ tự động áp dụng ưu đãi giới thiệu. Khi ưu đãi giới thiệu kết thúc, cam kết 12 tháng của người đăng ký sẽ bắt đầu.
• Ưu đãi và ưu đãi thu hút khách hàng cũ: Thiết lập ưu đãi hoặc ưu đãi thu hút khách hàng cũ cho gói cam kết trong App Store Connect. Sau đó thêm các ưu đãi vào Adapty và đặt App Store plan của chúng thành Monthly with 12-month commitment. Một hàng paywall chỉ hiển thị các ưu đãi dành cho gói thanh toán của chính nó. Nếu bạn không dùng paywall tùy chỉnh, bạn không cần thêm các ưu đãi vào Adapty.
• Mã ưu đãi: Thiết lập mã ưu đãi cho gói cam kết trong App Store Connect.

4. Thêm vào paywall tùy chỉnh

1. Trong paywall tùy chỉnh, thêm sản phẩm theo năm và đặt Billing plan thành Monthly. Để cũng bán gói trả trước trên cùng paywall đó, thêm sản phẩm theo năm một lần nữa với billing plan Upfront.
   • Để cung cấp ưu đãi trả trước cho người dùng mua gói trả trước — trên phiên bản SDK cũ hơn, hoặc khi gói cam kết không áp dụng — hãy chọn nó trong Fallback offer.
2. Trong ứng dụng của bạn, hiển thị giá từ product.subscriptionPricingTerms. Với những người dùng có thể mua gói cam kết, Adapty SDK trả về giá của gói đó. Với những người dùng còn lại, SDK trả về giá của gói trả trước:
   • Để biết gói nào SDK đã trả về, kiểm tra product.subscriptionPricingTerms?.billingPlan. Giá trị là .monthly cho gói cam kết và .upFront cho gói trả trước.
   • Để hiển thị giá theo kỳ thanh toán, dùng subscriptionPricingTerms.localizedBillingPrice và subscriptionPricingTerms.billingPeriod.
   • Để hiển thị tổng giá theo năm, dùng subscriptionPricingTerms.commitmentInfo.localizedPrice và subscriptionPricingTerms.commitmentInfo.period. Với gói cam kết, product.localizedPrice và product.subscriptionPeriod trả về các giá trị theo năm tương tự.

Người dùng không thể mua gói cam kết trong các trường hợp sau:

• Phiên bản hệ điều hành hoặc quốc gia không được hỗ trợ: Thiết bị Apple của người dùng chạy phiên bản hệ thống thấp hơn 26.4, hoặc gói đăng ký không có sẵn ở quốc gia trong App Store của họ. Adapty SDK sẽ trả về giá của gói trả trước.
• Đang có gói đăng ký trả trước: StoreKit báo cáo rằng người dùng đã đăng ký. Để chuyển gói, người đăng ký sử dụng cài đặt gói đăng ký Apple của họ.
• In-app purchase được quảng bá: Người dùng chọn sản phẩm trong App Store, sau đó Adapty SDK bắt đầu quá trình mua trong ứng dụng của bạn. Đối với những giao dịch mua này, SDK chỉ hỗ trợ gói trả trước.

Để ngừng cung cấp gói cam kết, trong các paywall tùy chỉnh của bạn, hãy đặt Billing plan của sản phẩm theo năm thành Upfront, hoặc xóa hàng Monthly. Bạn không thể bỏ chọn hộp kiểm Offer monthly payments with a 12-month commitment trong Adapty. Những người đăng ký hiện tại vẫn sẽ gia hạn vào một cam kết mới mỗi năm, trừ khi bạn nhấp vào Remove Monthly Billing cho gói đăng ký hàng năm trong App Store Connect. Những người đăng ký đã cam kết vẫn tiếp tục thanh toán cho đến khi cam kết của họ kết thúc.

5. Kiểm tra kế hoạch trong sandbox

Làm theo hướng dẫn kiểm tra sandbox với hai tài khoản sandbox:

• Một tài khoản từ quốc gia có cung cấp gói thanh toán theo kỳ: Paywall sẽ hiển thị gói thanh toán theo kỳ với giá hàng tháng cùng tổng giá. Sau khi mua, hồ sơ người dùng sandbox sẽ có mức độ truy cập của sản phẩm theo năm.
• Một tài khoản Mỹ: Paywall chỉ hiển thị gói thanh toán trả trước.

Nếu code của bạn xử lý product ID từ webhook hoặc Server-side API, hãy xác minh rằng nó nhận các giao dịch mua commitment-plan dưới dạng <product_id>:monthly.

Để kiểm tra logic mua hàng cục bộ, hãy sử dụng StoreKit Testing trong Xcode 26.5 hoặc mới hơn. Các giao dịch mua trong StoreKit Testing không được gửi tới Adapty.

Khắc phục sự cố

• Hộp kiểm cho thanh toán hàng tháng bị thiếu: Hộp kiểm Offer monthly payments with a 12-month commitment chỉ xuất hiện trên sản phẩm Annual có App Store product ID. Nó sẽ ở trạng thái không hoạt động cho đến khi sản phẩm có Price (USD).
• Người dùng không thấy dùng thử miễn phí hoặc ưu đãi khác cho gói commitment: Trong App Store Connect, mỗi ưu đãi thuộc về một gói thanh toán. Thiết lập ưu đãi cho gói commitment. Đối với ưu đãi quảng cáo hoặc ưu đãi thu hút khách hàng cũ, hãy đặt App Store plan của ưu đãi trong Adapty thành Monthly with 12-month commitment.
• Mọi người dùng đều thấy giá trả trước: Hãy xác minh cả hai điều sau:
  • Ứng dụng được build bằng Xcode 26.5 trở lên. Với phiên bản Xcode cũ hơn, Adapty SDK luôn trả về giá của gói trả trước.
  • Trong custom paywall, Billing plan của sản phẩm hàng năm được đặt là Monthly.
• Một số người dùng thấy giá trả trước: Những người dùng đó không thể mua gói commitment.
• Paywall hiển thị tổng giá hàng năm thay vì giá theo từng kỳ: Đối với gói commitment, product.localizedPrice trả về tổng giá hàng năm. Để hiển thị giá theo từng kỳ, hãy dùng subscriptionPricingTerms.localizedBillingPrice.