<!--
{
  "documentType" : "article",
  "framework" : "AppStoreConnectAPI",
  "identifier" : "/documentation/AppStoreConnectAPI/promoted-purchases",
  "metadataVersion" : "0.1.0",
  "role" : "collectionGroup",
  "title" : "Promoted Purchases"
}
-->

# Promoted Purchases

Manage the in-app purchase or auto-renewable subscription that’s promoted on an app listing in the App Store.

## Topics

### Endpoints

[`POST /v1/promotedPurchases`](/documentation/AppStoreConnectAPI/POST-v1-promotedPurchases)

Add an existing in-app purchase or auto-renewable subscription to the promoted in-app purchases on an app listing in the App Store.

[`GET /v1/apps/{id}/promotedPurchases`](/documentation/AppStoreConnectAPI/GET-v1-apps-_id_-promotedPurchases)

Get a list of promoted in-app purchases, including promoted auto-renewable subscriptions, for an app.

[`GET /v1/apps/{id}/relationships/promotedPurchases`](/documentation/AppStoreConnectAPI/GET-v1-apps-_id_-relationships-promotedPurchases)

Get a list of resource IDs representing promoted purchases for an auto-renewable subscription.

[`GET /v1/promotedPurchases/{id}`](/documentation/AppStoreConnectAPI/GET-v1-promotedPurchases-_id_)

Get details about a specific promoted in-app purchase.

[`PATCH /v1/promotedPurchases/{id}`](/documentation/AppStoreConnectAPI/PATCH-v1-promotedPurchases-_id_)

Update the visibility of a promoted in-app purchase.

[`PATCH /v1/apps/{id}/relationships/promotedPurchases`](/documentation/AppStoreConnectAPI/PATCH-v1-apps-_id_-relationships-promotedPurchases)

Update the order of promoted purchases.

[`DELETE /v1/promotedPurchases/{id}`](/documentation/AppStoreConnectAPI/DELETE-v1-promotedPurchases-_id_)

Remove a promotion for an in-app purchase or auto-renewable subscription from the App Store listing.

### Objects

[`PromotedPurchaseResponse`](/documentation/AppStoreConnectAPI/PromotedPurchaseResponse)

The response body for endpoints that read or modify a promoted in-app purchase or subscription.

[`PromotedPurchasesResponse`](/documentation/AppStoreConnectAPI/PromotedPurchasesResponse)

The response body for endpoints that list promoted in-app purchases and subscriptions for an app.

[`PromotedPurchaseCreateRequest`](/documentation/AppStoreConnectAPI/PromotedPurchaseCreateRequest)

The request body you use to create a promoted purchase.

[`PromotedPurchaseUpdateRequest`](/documentation/AppStoreConnectAPI/PromotedPurchaseUpdateRequest)

The request body you use to update a promoted purchase update request.

[`AppPromotedPurchasesLinkagesRequest`](/documentation/AppStoreConnectAPI/AppPromotedPurchasesLinkagesRequest)

The request body for updating the ordered list of in-app purchases and subscriptions promoted on an app’s product page.

[`AppPromotedPurchasesLinkagesResponse`](/documentation/AppStoreConnectAPI/AppPromotedPurchasesLinkagesResponse)

A response containing the resource identifiers of in-app purchases and subscriptions promoted on an app’s product page.


---

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)