Auto-Renewable Subscriptions
In-App Purchase provides a standardized way to implement auto-renewable subscriptions. Auto-renewable subscriptions have a few notable characteristics:
When you configure an auto-renewable subscription in iTunes Connect, you also configure the duration for the subscription and other marketing options.
Auto-renewable subscriptions are restored automatically using the same Store Kit functions used to restore non-consumable products. The original purchase transaction as well a transaction for each renewal are sent to your application. See “Restoring Transactions.”
When your server verifies a receipt with the App Store and the subscription is both active and has been renewed by the App Store, the App Store returns an updated receipt to your application.
Adding Auto-Renewable Subscriptions to Your Store
To implement auto-renewable subscriptions, follow these steps:
Connect to iTunes Connect and use it to create a new shared secret. A shared secret is a password that your server must provide when validating receipts for auto-renewable subscriptions. This shared secret provides an additional layer of security to your transactions with the App Store. See iTunes Connect Developer Guide.
Configure new products in iTunes Connect with the new auto-renewable subscription type.
Modify your server’s receipt verification code so that it adds the shared secret to the JSON data it sends to the App Store. Your server’s verification code must parse the response to determine whether the subscription has expired. If the subscription has been renewed by the user, the most current receipt is also returned to your server.
Designing your Client Application
In most cases, your client application should require minimal changes to support auto-renewable subscriptions. In fact, your client application is now made simpler, as you can use the same code to recover auto-renewable subscriptions as you do to recover non-consumable products. Your application receives a separate transaction for each period of time where the subscription was renewed; your application should verify each receipt separately.
Verifying an Auto-renewable Subscription Receipt
Verifying a receipt for an auto-renewable subscription is almost identical to the process described in “Verifying Store Receipts.” Your application creates a JSON object and posts it to the App Store. The JSON object for an auto-renewable subscription receipt must include a second parameter — the shared secret you created earlier on iTunes Connect:
{ |
"receipt-data" : "(receipt bytes here)", |
"password" : "(shared secret bytes here)" |
} |
The response includes a status field that indicates whether the receipt was successfully validated.
{ |
"status" : 0, |
"receipt" : { (receipt here) }, |
"latest_receipt" : "(base-64 encoded receipt here)", |
"latest_receipt_info" : { (latest receipt info here) } |
} |
If the user’s receipt was valid and the subscription is active, the status field holds 0, and the receipt field is populated with the decoded receipt data. If your server receives a non-zero status value, use Table 7-1 to interpret non-zero status codes.
Status Code | Description |
|---|---|
21000 | The App Store could not read the JSON object you provided. |
21002 | The data in the receipt-data property was malformed. |
21003 | The receipt could not be authenticated. |
21004 | The shared secret you provided does not match the shared secret on file for your account. |
21005 | The receipt server is not currently available. |
21006 | This receipt is valid but the subscription has expired. When this status code is returned to your server, the receipt data is also decoded and returned as part of the response. |
21007 | This receipt is a sandbox receipt, but it was sent to the production service for verification. |
21008 | This receipt is a production receipt, but it was sent to the sandbox service for verification. |
The receipt field on the JSON object holds the parsed information from the receipt. The receipt data for an auto-renewable subscription includes one additional key, and some other key previously described in Table 5-1 are modified slightly for subscriptions. See Table 7-2 for details on the new and modified keys.
Key | Description |
|---|---|
| The expiration date of the subscription receipt, expressed as the number of milliseconds since January 1, 1970, 00:00:00 GMT. |
| This holds the transaction identifier for the initial purchase. All subsequent renewals of this subscription and recovered transactions all share this identifier. |
| This holds the purchase date for the initial purchase; it represents the start date for the subscription. |
| This holds the billing date when this transaction occurred. For a transaction for a renewable subscription, this would be the date when the subscription was renewed. If the receipt being parsed by the App Store was the latest receipt for this subscription, this field holds the date when this subscription was most recently renewed. |
In addition to the receipt_data field, the response may also include two new fields. If the user’s subscription is active and was renewed by a transaction that took place after the receipt your server sent to the App Store, the latest_receipt field includes a base-64 encoded receipt for the last renewal for this subscription. The decoded data for this new receipt is also provided in the latest_expired_receipt_info field. Your server can use this new receipt to maintain a record of the most recent renewal.
© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)