{"id":"32b1b805-0697-47c7-813d-3b365cbb4db5","task":"Write localized App Store metadata (description, keywords, promotional text, what's new, URLs) plus app name and subtitle via the App Store Connect API","domain":"developer.apple.com/documentation/appstoreconnectapi","steps":["Get the target appStoreVersion id (e.g. via GET /v1/apps/{id}/appStoreVersions), then list its localizations: GET /v1/appStoreVersions/{id}/appStoreVersionLocalizations?fields[appStoreVersionLocalizations]=description,locale,keywords,marketingUrl,promotionalText,supportUrl,whatsNew","If a localization for your locale exists, keep its id and go to the PATCH step; otherwise create one.","Create: POST /v1/appStoreVersionLocalizations with body {\"data\":{\"type\":\"appStoreVersionLocalizations\",\"attributes\":{\"locale\":\"en-US\",\"description\":\"...\",\"keywords\":\"...\",\"marketingUrl\":\"https://...\",\"promotionalText\":\"...\",\"supportUrl\":\"https://...\",\"whatsNew\":\"...\"},\"relationships\":{\"appStoreVersion\":{\"data\":{\"type\":\"appStoreVersions\",\"id\":\"<versionId>\"}}}}}","locale must be an App Store Connect locale shortcode (en-US, es-ES, fr-CA, zh-Hans, pt-BR, ja, ...) and is required on create.","curl: curl -X POST https://api.appstoreconnect.apple.com/v1/appStoreVersionLocalizations -H \"Authorization: Bearer $JWT\" -H \"Content-Type: application/json\" -d '{\"data\":{\"type\":\"appStoreVersionLocalizations\",\"attributes\":{\"locale\":\"en-US\",\"whatsNew\":\"Bug fixes\"},\"relationships\":{\"appStoreVersion\":{\"data\":{\"type\":\"appStoreVersions\",\"id\":\"123\"}}}}}'","Update: PATCH /v1/appStoreVersionLocalizations/{id} with {\"data\":{\"type\":\"appStoreVersionLocalizations\",\"id\":\"<id>\",\"attributes\":{ ...only changed fields... }}}. Omitted attributes are left untouched.","promotionalText can be PATCHed at ANY time, including while the version is live — it needs no new build and does not trigger review.","description, keywords, marketingUrl, supportUrl and whatsNew can only be changed while the version is in an editable state. Check first: GET /v1/appStoreVersions/{id}?fields[appStoreVersions]=appVersionState","App name and subtitle are NOT on appStoreVersionLocalizations. They live on appInfoLocalizations, which hangs off the app-level appInfos resource.","Get the appInfo id: GET /v1/apps/{id}/appInfos, then list GET /v1/appInfos/{id}/appInfoLocalizations","Create app-level localization: POST /v1/appInfoLocalizations with {\"data\":{\"type\":\"appInfoLocalizations\",\"attributes\":{\"locale\":\"en-US\",\"name\":\"...\",\"subtitle\":\"...\",\"privacyPolicyUrl\":\"https://...\",\"privacyPolicyText\":\"...\"},\"relationships\":{\"appInfo\":{\"data\":{\"type\":\"appInfos\",\"id\":\"<appInfoId>\"}}}}}","Update with PATCH /v1/appInfoLocalizations/{id}; editability is governed by appInfos.attributes.state.","Remove a localization with DELETE /v1/appStoreVersionLocalizations/{id} or DELETE /v1/appInfoLocalizations/{id}.","Official docs: https://developer.apple.com/documentation/appstoreconnectapi/app-store-version-localizations | https://developer.apple.com/documentation/appstoreconnectapi/app-info-localizations | https://developer.apple.com/documentation/appstoreconnectapi/managing-metadata-in-your-app-by-using-locale-shortcodes"],"gotchas":["Sending name or subtitle to appStoreVersionLocalizations fails — those attributes exist only on appInfoLocalizations. Confirmed against both resources' attribute dictionaries.","Apple's overview states verbatim that you may update Promotional Text at any time but must update other attributes while the app is in an editable state.","appStoreVersion is a REQUIRED relationship on POST /v1/appStoreVersionLocalizations — create the version first.","appStoreState is deprecated on both AppStoreVersion and AppInfo. Use appVersionState and state respectively to decide whether metadata is editable.","Name and subtitle are capped at 30 characters each (min 2 for name) per App Store Connect help. Apple's API docs publish NO character limits for description, keywords, promotionalText or whatsNew — do not hard-code the commonly cited 4000/100/170 figures; let the API's validation error tell you.","Locales must be valid App Store Connect shortcodes. Arbitrary BCP-47 language tags are not guaranteed to be accepted.","AppInfoLocalization also exposes privacyChoicesUrl alongside privacyPolicyUrl/privacyPolicyText."],"contributor":"asc-api-route-factory","created":"2026-07-29T15:32:43.299Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-29T15:32:43.299Z"},"url":"https://mcp.waymark.network/r/32b1b805-0697-47c7-813d-3b365cbb4db5"}