跳到内容

App Store Connect API

使用 App Store Connect API 修改价格

App Store Connect 中定价界面能做的一切,都可以通过 API 完成。这是一份地图:有哪些资源、请求长什么样、一次全球调价需要多少次调用,以及实际中会出什么问题。

更新于 阅读约需 7 分钟

简短回答

要用 App Store Connect API 修改价格,先获取产品在基础国家或地区的价格点,选出对应新价格的价格点,然后创建价格计划:App 用 POST /v1/appPriceSchedules,App 内购买项目用 POST /v1/inAppPurchasePriceSchedules,订阅则对每个国家或地区各调用一次 POST /v1/subscriptionPrices。使用团队 API 密钥签发的 JWT 进行身份验证。

身份验证

每个请求都带有一个承载令牌 JWT,由你用 API 密钥的 .p8 私钥签发(Apple:生成令牌):

  • 头部:alg = ES256,kid = 你的 Key ID,typ = JWT。
  • 载荷:iss = 你的 Issuer ID,iat = 当前时间,exp = 最晚 20 分钟之后,aud = appstoreconnect-v1。可选的 scope 可以把令牌限制在列出的 GET 请求上。
  • 在令牌过期之前,多个请求可复用同一个令牌;Apple 为了性能推荐这样做。耗时较长的任务需要定期生成新令牌。
  • 该密钥需要能够管理定价的角色:管理员或 App 管理(Apple 的帮助页面把账户持有人、管理员或 App 管理列为所需角色)。创建方法见 API 密钥指南。

资源

产品价格点价格均衡创建价格变更
App`GET /v1/apps/{id}/appPricePoints`?filter[territory]=USA`GET /v3/appPricePoints/{id}/equalizations``POST /v1/appPriceSchedules` — 基础国家或地区加手动价格
App 内购买项目`GET /v2/inAppPurchases/{id}/pricePoints``GET /v1/inAppPurchasePricePoints/{id}/equalizations``POST /v1/inAppPurchasePriceSchedules` — 必须提供基础国家或地区
订阅`GET /v1/subscriptions/{id}/pricePoints` — 始终带上 filter[territory]`GET /v1/subscriptionPricePoints/{id}/equalizations``POST /v1/subscriptionPrices` — 每个国家或地区一次
国家或地区`GET /v1/territories`—只读:175 个店面及其货币

每个价格点都有 customerPrice 和你的 proceeds。某个价格点的均衡结果,就是所有其他店面中与之对应的价格点——即 Apple 对该基础价格的全球定价,你无需自己做任何汇率计算。对于同时提供按月和预付方案类型的订阅,Apple 还记录了 adjustedEqualizations(Apple:跨国家或地区配置订阅价格)。读取当前状态可使用 GET /v1/apps/{id}/appPriceSchedule,订阅则使用 GET /v1/subscriptions/{id}/prices。

请求长什么样

App 价格计划是一个 JSON:API 文档,价格以内联方式创建。关键部分如下:

位置字段取值
datatypeappPriceSchedules
data.relationshipsapp你的 App 的 ID
data.relationshipsbaseTerritory例如 USA
data.relationshipsmanualPrices引用 included 中的价格,使用 ${price-1} 这样的临时 ID
included[]typeappPrices(App 内购买项目:inAppPurchasePrices)
included[].attributesstartDate, endDate表示“现在”和“无结束日期”时为 null,也可以是一个日期
included[].relationshipsappPricePoint该国家或地区的价格点 ID

没有手动价格的国家或地区,会采用由基础价格推算出的 Apple 自动价格。订阅价格更简单:type 为 subscriptionPrices,属性有 startDate 和 preserveCurrentPrice(若提供方案类型,还有 planType),以及指向订阅、国家或地区和 subscriptionPricePoint 的关系。

分步完成一次全球调价

  1. 列出一次国家或地区并缓存;它们很少变化。
  2. 对每个产品,获取基础国家或地区的价格点(每页 200 个),找到与新基础价格对应的那个。
  3. 如果各地都采用 Apple 的定价,到此为止:对于 App 和 App 内购买项目,仅基础价格点就足够了。如果要使用自己的区域价格,则为每个店面算出目标价格并取整——简便的做法是在基础货币中取整,然后沿用该价格点的均衡结果(取整的原理)。
  4. App 和 App 内购买项目:用基础国家或地区和全部手动价格 POST 一份计划。订阅:对每个店面各 POST 一个 subscriptionPrices,附上开始日期和对现有订阅者的政策。
  5. 对 429 和 5xx 采用退避重试;记录每个创建的资源,作为审计依据。
  6. 回读计划或价格,并在 App Store Connect 中抽查几个店面。

需要多少次请求?

举个实际例子:2 个 App、10 个 App 内购买项目和 4 个订阅,使用 4 个区域价格档重新定价。Apple 的速率限制示例是每个密钥每滚动小时 3,500 次请求,并说明实际限制会有所不同——请在每个响应中读取 X-Rate-Limit 头(Apple:速率限制)。

步骤计算请求数
国家或地区一次1
基础价格点16 个产品 × 约 5 页≈ 80
价格均衡16 个产品 × 4 个价格档价格点≈ 64
App 和内购计划12 个产品 × 112
订阅价格4 个订阅 × 175 个店面700
合计≈ 857

订阅占了大头:Apple 指出,没有用于批量应用均衡后订阅价格的端点。如果产品目录翻倍,再加上重试和一轮验证,就接近示例中的小时上限——所以要控制任务节奏,而不是用紧凑的循环疯狂发送。

常见陷阱

  • 对价格计划发送 POST 会替换整个 App 或 App 内购买项目的计划。要包含你想保留的每一个手动价格,而不只是发生变化的——遗漏的都会回落到 Apple 的自动价格。
  • 要为 App 或内购安排未来的变更,请先发送当前的手动价格,并让 endDate 等于新的 startDate,再发送新的价格。相邻的两个区间若使用同一价格点会被拒绝(“Adjacent intervals cannot have the same price point”),所以没有变化的国家或地区应作为一个无结束日期的条目发送。
  • 订阅在每个国家或地区最多保留一个未来价格。创建新的之前,先用 `DELETE /v1/subscriptionPrices/{id}` 删除排队中的那个。
  • 没有开始日期的订阅价格是初始价格。订阅通过审核后,后续价格必须带 startDate,否则 API 会返回 409 状态错误。
  • 订阅降价对现有订阅者生效,并且任何订阅变更一旦生效就无法撤销。涨价可能需要征得同意——参见提高订阅价格。
  • 价格点列表很大。始终按国家或地区筛选,并分页获取。
  • 这些端点的令牌最长有效 20 分钟;耗时较长的任务必须重新签发。
  • 变更最长可能需要一小时才会在沙盒中显示。
  • API 不会问“你确定吗?”。审核环节要自己搭建。

安全地测试定价脚本

你的 App Store Connect 账户没有预发布副本,所以安全机制要内置在脚本本身:

  • 给脚本加一个试运行标志:计算所有内容并打印一张包含产品、国家或地区、当前价格和新价格的表格,但不发送任何内容。
  • 写入之前,先读取线上的计划或价格,与你的方案做对比;跳过已经是目标价格的国家或地区。
  • 第一次真实写入,选一个尚未促销的产品,或只写一个国家或地区,然后读回确认。
  • 为每个国家或地区写一行日志,记录新旧价格点。一旦出错,靠这份日志就能把价格改回去。
  • 把密钥放在密钥存储中,绝不要放进代码仓库,并给脚本单独的密钥,这样你可以独立撤销它。

不用写脚本:RepriceCat

RepriceCat 实际上就是把本指南做成了产品。你连接自己的团队密钥(加密存储,随时可撤销),它会获取价格点,把价格档的价格取整到有效的价格点,构建价格计划——包括为定时变更保留当前价格——并根据速率限制自行控制节奏。

  • 发送任何内容之前,先提供“产品 × 国家或地区”的审核表,显示当前价格 → 新价格;还有不发送任何内容的试运行。
  • 一次变更可涵盖跨多个 App 的最多 200 个产品,立即生效或在指定日期生效。
  • 失败的国家或地区会列出 Apple 给出的原因,并可单独重新发送;每次变更都按国家或地区记录,并支持回滚。
  • 电子表格往返:把价格导出为 XLSX 或 CSV,编辑后再导入。

在自己开发和购买现成工具之间犹豫?请阅读 RepriceCat 与 API 脚本对比,或免费体验一个月。

常见问题

App Store Connect API 密钥需要什么角色才能修改价格?

管理员或 App 管理。Apple 的定价帮助页面把账户持有人、管理员或 App 管理列为可以管理价格的角色;开发者、市场营销、销售或财务角色的密钥不可以。

API 能在一次请求中修改所有国家或地区的价格吗?

对于 App 和 App 内购买项目可以:一份价格计划就包含基础国家或地区和全部手动价格。对于订阅,每个国家或地区都是独立的 subscriptionPrices 资源,所以全球调价意味着每个订阅最多 175 次请求。

如何通过 API 获取 Apple 均衡后的价格?

找到你基础价格对应的价格点,然后调用它的价格均衡端点。它会返回其他每个店面中可比的价格点,你可以直接使用,也可以把它作为区域价格档取整后的价格。

定价调用有沙盒或试运行模式吗?

没有。价格计划会作用于真实账户。请仔细审核计算出的批量内容,在尚未上线的产品上测试,或使用自带试运行的工具。

App Store Connect API 的速率限制是多少?

限制按每个 API 密钥在滚动一小时内计算,并在每个响应的 X-Rate-Limit 头中给出。Apple 的示例是每小时 3,500 次请求,但说明实际限制会有所不同;超出则返回 HTTP 429。

如何通过 API 取消已安排的价格变更?

对于订阅,删除待生效的 subscriptionPrices 资源。对于 App 或 App 内购买项目,提交一份不含该未来条目的新计划,注意 POST 会替换整个计划。

试一试

从一个基准价格为每个国家/地区重新定价

价格档、自动对齐价格点、一张检查表、一次确认,全部通过 App Store Connect API 完成。首月免费,之后每个 App 每月 $1。