<!--
{
  "documentType" : "article",
  "framework" : "AppStoreConnectAPI",
  "identifier" : "/documentation/AppStoreConnectAPI/working-with-in-app-purchase-versions",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Working with In-App Purchase versions"
}
-->

# Working with In-App Purchase versions

Manage draft versions of an In-App Purchase’s localized metadata and review images before submitting for App Review.

## Discussion

An In-App Purchase version is a draft container that groups the localized metadata and review images that go through App Review together. Create a version, attach localizations and images to it, then submit the version through the review submissions workflow. The parent In-App Purchase resource holds properties that stay stable across versions — its product ID, In-App Purchase type, and pricing — while each version captures the reviewable metadata for a single review cycle.

> Note:
> The pre-4.4.1 workflow that posts localizations and images directly to the In-App Purchase (`POST /v1/inAppPurchaseLocalizations`, `POST /v1/inAppPurchaseImages`) is deprecated as of 4.4.1 but remains available for existing integrations. For guidance on moving to the version-based workflow, see <doc://com.apple.appstoreconnectapi/documentation/AppStoreConnectAPI/migrating-in-app-purchase-metadata-to-v2>.

### Understand the version lifecycle

A version moves through these states, exposed on `InAppPurchaseVersion/Attributes/state`:

- `PREPARE_FOR_SUBMISSION`: The version is open for editing. You can add, change, or remove localizations and images.
- `READY_FOR_REVIEW`: The version belongs to a review submission and is waiting for you to mark that submission `submitted`.
- `WAITING_FOR_REVIEW`: You submitted the review submission, and the version is queued.
- `IN_REVIEW`: App Review is actively reviewing the version.
- `ACCEPTED` or `APPROVED`: The version passed review.
- `REJECTED` or `DEVELOPER_REJECTED`: App Review rejected the version, or you withdrew it.
- `REPLACED_WITH_NEW_VERSION`: A newer version supersedes this one.

Versions are read-only after creation. To change a version’s contents, create a new version.

### Create a version

Create a draft version with `POST /v1/inAppPurchaseVersions` ([`Create an In-App Purchase version`](/documentation/AppStoreConnectAPI/POST-v1-inAppPurchaseVersions)). Relate it to the In-App Purchase whose metadata you’re updating:

```json
{
  "data": {
    "type": "inAppPurchaseVersions",
    "relationships": {
      "inAppPurchase": {
        "data": {
          "type": "inAppPurchases",
          "id": "6446452615"
        }
      }
    }
  }
}
```

The response returns the new version’s `id` and a `state` of `PREPARE_FOR_SUBMISSION`. Note the `id` — every subsequent step references it.

### Attach a localization to the version

Add a localized display name and description with `POST /v2/inAppPurchaseLocalizations` ([`Create an In-App Purchase localization`](/documentation/AppStoreConnectAPI/POST-v2-inAppPurchaseLocalizations)). The payload relates the localization to the version, not the parent In-App Purchase:

```json
{
  "data": {
    "type": "inAppPurchaseLocalizations",
    "attributes": {
      "locale": "en-US",
      "name": "Seattle Neighborhood Coffee Map",
      "description": "This is a neighborhood map for helping to find awesome coffee shops."
    },
    "relationships": {
      "version": {
        "data": {
          "type": "inAppPurchaseVersions",
          "id": "${inAppPurchaseVersionId}"
        }
      }
    }
  }
}
```

Repeat for each locale you support. To list the localizations attached to a version, use `GET /v1/inAppPurchaseVersions/{id}/localizations` ([`List localizations for an In-App Purchase version`](/documentation/AppStoreConnectAPI/GET-v1-inAppPurchaseVersions-_id_-localizations)).

### Attach a review image to the version

An In-App Purchase version can carry review images that show the promotion image customers see on the App Store product page. Reserve, upload, and commit each image in three steps.

Reserve an image with `POST /v2/inAppPurchaseImages` ([`Create an In-App Purchase image`](/documentation/AppStoreConnectAPI/POST-v2-inAppPurchaseImages)):

```json
{
  "data": {
    "type": "inAppPurchaseImages",
    "attributes": {
      "fileName": "coffee-map-promo.png",
      "fileSize": 245670
    },
    "relationships": {
      "version": {
        "data": {
          "type": "inAppPurchaseVersions",
          "id": "${inAppPurchaseVersionId}"
        }
      }
    }
  }
}
```

The response returns an `id` for the image and a set of `uploadOperations` describing how to `PUT` the file bytes.

Upload the image bytes to the URL from `uploadOperations`. Then commit the upload with `PATCH /v2/inAppPurchaseImages/{id}` ([`Modify an In-App Purchase image`](/documentation/AppStoreConnectAPI/PATCH-v2-inAppPurchaseImages-_id_)):

```json
{
  "data": {
    "type": "inAppPurchaseImages",
    "id": "${inAppPurchaseImageId}",
    "attributes": {
      "uploaded": true
    }
  }
}
```

Read image metadata with `GET /v2/inAppPurchaseImages/{id}` ([`Read In-App Purchase image information`](/documentation/AppStoreConnectAPI/GET-v2-inAppPurchaseImages-_id_)). Remove an image with `DELETE /v2/inAppPurchaseImages/{id}` ([`Delete an In-App Purchase image`](/documentation/AppStoreConnectAPI/DELETE-v2-inAppPurchaseImages-_id_)).

For more on the reserve-upload-commit pattern, see [Uploading Assets to App Store Connect](/documentation/AppStoreConnectAPI/uploading-assets-to-app-store-connect).

### List all versions for an In-App Purchase

To see every version on a parent In-App Purchase, use `GET /v2/inAppPurchases/{id}/versions` ([`List the versions of an In-App Purchase`](/documentation/AppStoreConnectAPI/GET-v2-inAppPurchases-_id_-versions)). The response includes each version’s state, so you can find the current draft, the most recently approved version, and any versions currently in review.

### Submit the version

Submit a completed version through the review submissions workflow. Create a review submission for the app, add the version as an item, and mark the submission as `submitted`. For step-by-step instructions, see [Managing In-App Purchases](/documentation/AppStoreConnectAPI/managing-in-app-purchases).

When you mark the submission `submitted`, the version moves from `READY_FOR_REVIEW` to `WAITING_FOR_REVIEW`. Poll `GET /v1/inAppPurchaseVersions/{id}` ([`Read In-App Purchase version information`](/documentation/AppStoreConnectAPI/GET-v1-inAppPurchaseVersions-_id_)) to watch it continue to `IN_REVIEW` and then `APPROVED` or `REJECTED`.

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)