App Store Connect API
使用 App Store Connect API 修改价格
App Store Connect 中定价界面能做的一切,都可以通过 API 完成。这是一份地图:有哪些资源、请求长什么样、一次全球调价需要多少次调用,以及实际中会出什么问题。
简短回答
要用 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 文档,价格以内联方式创建。关键部分如下:
| 位置 | 字段 | 取值 |
|---|---|---|
data | type | appPriceSchedules |
data.relationships | app | 你的 App 的 ID |
data.relationships | baseTerritory | 例如 USA |
data.relationships | manualPrices | 引用 included 中的价格,使用 ${price-1} 这样的临时 ID |
included[] | type | appPrices(App 内购买项目:inAppPurchasePrices) |
included[].attributes | startDate, endDate | 表示“现在”和“无结束日期”时为 null,也可以是一个日期 |
included[].relationships | appPricePoint | 该国家或地区的价格点 ID |
没有手动价格的国家或地区,会采用由基础价格推算出的 Apple 自动价格。订阅价格更简单:type 为 subscriptionPrices,属性有 startDate 和 preserveCurrentPrice(若提供方案类型,还有 planType),以及指向订阅、国家或地区和 subscriptionPricePoint 的关系。
分步完成一次全球调价
- 列出一次国家或地区并缓存;它们很少变化。
- 对每个产品,获取基础国家或地区的价格点(每页 200 个),找到与新基础价格对应的那个。
- 如果各地都采用 Apple 的定价,到此为止:对于 App 和 App 内购买项目,仅基础价格点就足够了。如果要使用自己的区域价格,则为每个店面算出目标价格并取整——简便的做法是在基础货币中取整,然后沿用该价格点的均衡结果(取整的原理)。
- App 和 App 内购买项目:用基础国家或地区和全部手动价格 POST 一份计划。订阅:对每个店面各 POST 一个
subscriptionPrices,附上开始日期和对现有订阅者的政策。 - 对 429 和 5xx 采用退避重试;记录每个创建的资源,作为审计依据。
- 回读计划或价格,并在 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 个产品 × 1 | 12 |
| 订阅价格 | 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 会替换整个计划。