Managing the life cycle of monthly subscriptions with a 12-month commitment

Handle renewals, cancellations, billing issues, refund requests, and price changes, and test subscriptions with a commitment plan.

Overview

A monthly subscription with a 12-month commitment is an auto-renewable subscription that bills customers monthly and has a yearly commitment. Unlike standard subscriptions that bill customers up front, its (billingPlanType) in Transaction is monthly.

For more information on configuring, merchandising, purchasing, and entitling a monthly subscription with a 12-month commitment, see Supporting monthly subscriptions with a 12-month commitment.

Manage subscription renewals

A monthly subscription with a 12-month commitment automatically bills monthly. Process the resulting transaction and enable access to content the same way as for standard subscriptions. When subscriptions renew, your server receives a DID_RENEW notification (notificationType) at your App Store Server Notifications V2 endpoint. Your app receives a transaction through the updates listener.

The following fields in the transaction provide additional information about the commitment plan:

Field	Structure	Description
Billingplantype	Transaction	A value of Monthly indicates a commitment plan.
Willautorenew	Renewalinfo	A Boolean value that indicates whether the next billing period will renew. This field behaves the same as for standard subscriptions.
Willautorenew	Commitmentinfo Swift.struct	A Boolean value that indicates whether the subscription will renew at the end of the 12-month commitment period.

When the 12th billing period completes, a value of 1 for willAutoRenew indicates that the subscription automatically renews. The App Store Server Notifications sends a DID_RENEW notification. If the renewal is for a monthly subscription with a 12-month commitment, period 1 of the new commitment begins. The renewal may apply to a different subscription, not necessarily one with a 12-month commitment.

Manage subscription cancellation during a commitment

When a customer cancels a monthly subscription with a 12-month commitment, they’re canceling the renewal of the commitment, not the remaining payments within the current term. Billing continues through all remaining periods. When a customer cancels the subscription mid-period, the following occurs:

The App Store server sets willAutoRenew in the commitment information (Product.SubscriptionInfo.RenewalInfo.CommitmentInfo) to 0, to indicate the commitment doesn’t renew when the term ends.
The willAutoRenew in the subscription renewal info (renewalInfo) remains 1, indicating that monthly billing continues for the remaining periods of the current commitment.
App Store Server Notifications sends a DID_CHANGE_RENEWAL_STATUS notificationType with an AUTO_RENEW_DISABLED subtype to your server.

App Store Server Notifications continues to send DID_RENEW notifications for each remaining billing period. Continue providing access to the subscription through the end of the commitment period. After the 12th and final period, the App Store server sends an EXPIRED notificationType. Access ends here.

When you receive a DID_CHANGE_RENEWAL_STATUS notification, check the billing plan type on the transaction first:

If the billing plan type is MONTHLY, read commitmentAutoRenewStatus to confirm the commitment doesn’t renew. Don’t revoke access to the subscription; continue to honor all remaining billing periods.
If the billing plan type is BILLED_UPFRONT, the subscription is a standard subscription. Apply your existing cancellation logic.

Manage subscription access during billing issues

When a monthly renewal fails due to a billing issue, the App Store automatically attempts to recover the payment. While the subscription is in a billing retry state, revoke access to the subscription, and restore it if billing recovers. If the App Store is unable to recover the payment within 90 days, the commitment ends and you revoke service permanently for that transaction.

App Store Server Notifications sends the following notifications (notificationType) to indicate the billing retry status:

Notification type	Transaction detail	App’s action
`DID_FAIL_TO_RENEW`	`isInBillingRetryPeriod` is `true`.	Revoke access to the subscription.
`DID_RENEW` with subtype `BILLING_RECOVERY`	`commitmentExpiresDate` shifts to a new billing date, reflecting the recovery date.	Restore access to the subscription.
`EXPIRED` with subtype `BILLING_RETRY`	`isInBillingRetryPeriod` is `false`.	Previously revoked access is final.

For more information on the transaction and subscription renewal information you receive with notifications, see JWSTransactionDecodedPayload and JWSRenewalInfoDecodedPayload.

After a billing issue recovery, read the commitmentExpiresDate from the latest transaction, because it differs from the original commitment end date. Subsequent renewals follow the shifted schedule.

Billing Grace Period doesn’t apply to monthly subscriptions with 12-month commitments. Revoke access to the subscription as soon as you receive a DID_FAIL_TO_RENEW notificationType.

Respond to refund consumption requests

When a customer submits a refund request for a subscription with a commitment plan, your server receives a CONSUMPTION_REQUEST notification at your App Store Server Notifications V2 endpoint.

Respond with the consumption information and your refund preference for that billing period. For more information on consumption requests, see Send Consumption Information.

Manage access after a refund

Customers may receive a refund after they request one, or after making changes to their subscription plan that cause a refund.

When a customer receives a refund for a monthly subscription with a 12-month commitment, the refund behavior depends on the billing period that the refund applies to, as follows:

If the refund applies to a prior billing period, the system revokes the transaction for that specific period, but the commitment continues unaffected. The customer remains subscribed and billing continues on schedule. Check the revocationDate on the affected transaction to detect the revocation, but don’t interpret it as a commitment cancellation.
If the refund applies to the current billing period, the commitment ends immediately. Check the revocationDate on the latest transaction — its presence indicates the current period has been revoked and the commitment has ended. Revoke access accordingly.

Manage price changes

Price changes for monthly subscriptions with 12-month commitments follow the same rules as standard annual subscriptions. For more information, see Managing Price Increases for Auto-Renewable Subscriptions.

Test the subscription using StoreKit Testing for Xcode

You can test your client-side implementation locally without a Sandbox Apple Account or an Apple Account using StoreKit Testing in Xcode. Testing monthly subscriptions with 12-month commitments is available starting in Xcode 26.5.

To configure the commitment-plan testing in Xcode:

Open your StoreKit configuration file in Xcode.
Select your 1-year auto-renewable subscription product.
Add the monthly billing plan type to the product’s configuration.
Set a monthly price for the plan.

With the configuration in place, you can:

Test your commitment-plan merchandising by verifying that your app returns the correct product and that both the monthly price and the total commitment price display correctly.
Test the purchase flow by initiating a purchase using the billingPlanType(.monthly) option and inspecting commitmentInfo on the resulting transaction.
Validate commitment progress UI by reading billingPeriodNumber, totalBillingPeriods, and the expiration date fields from the transaction.
Simulate a cancellation by canceling the subscription in the Transaction Manager. Confirm that your app continues to grant access to the subscription through the remaining billing periods. For more information, see Testing in-app purchases with StoreKit transaction manager in Xcode.
Test your entitlement logic by confirming your app uses expirationDate in Transaction for subscription-access decisions and only uses expirationDate in Transaction.CommitmentInfo to display the commitment progress.

For more information, see Setting up StoreKit Testing in Xcode.

Test your app in the sandbox environment

When you’re ready to validate your server-side implementation, test in the sandbox environment using a Sandbox Apple Account.

In the sandbox environment, you can:

Run the full 12-month commitment at an accelerated rate to validate the complete commitment life cycle end-to-end.
Validate your server-side logic with real signed transactions and App Store Server Notifications V2.
Test cancellation flows by canceling a commitment mid-period and verifying that your server and app correctly handle DID_CHANGE_RENEWAL_STATUS, continue granting access through remaining billing periods, and revoke access only after the final EXPIRED notification.
Test billing issues and recovery flows by simulating payment issues and verifying that your server revokes access on DID_FAIL_TO_RENEW, restores access on DID_RENEW BILLING_RECOVERY, and reads the updated commitmentExpiresDate from the recovered transaction.
Test a billing issue without a recovery by leaving the Allow Purchases & Renewal toggle off past the billing retry window. Verify that your server receives an EXPIRED notification type with subtype BILLING_RETRY. You would have already revoked access to the subscription based on a previously received DID_FAIL_TO_RENEW notification; the revocation is now final.