Overview: Automating Time-Based App Pricing
Whether planning a Black Friday discount, a launch-week promotional price, or an upcoming price increase across international storefronts, developers frequently ask: Can my AI coding assistant schedule an App Store price change to take effect automatically on a future date?
The answer is yes.
In the modern App Store Connect REST API, Apple does not require you to manually click buttons at midnight or leave a local script running on your Mac. Instead, Apple provides an authoritative scheduling resource called AppPriceSchedule.
When you configure an AppPriceSchedule, you declare a sequence of price points along with their future effective start dates (startDate) and optional end dates (endDate). Once Apple accepts the schedule, Apple's cloud edge servers execute the price transition automatically across 175 storefronts at the appointed date and time.
┌────────────────────────────────────────────────────────────────────────┐
│ APPLE PRICE SCHEDULE TIMELINE MODEL │
│ │
│ TODAY (e.g. Nov 15) DECEMBER 1 (Black Friday Promo) │
│ Current Base Price: $9.99 Scheduled Promo Price: $4.99 │
│ [Live on App Store] [startDate: "2026-12-01", auto-switch]│
│ │ │ │
│ └─────────────────┬──────────────────┘ │
│ ▼ │
│ JANUARY 2 (Promo Concludes) │
│ Scheduled Standard Price: $9.99 │
│ [startDate: "2026-01-02", returns to regular tier] │
└────────────────────────────────────────────────────────────────────────┘
Using FlightDeck MCP, your AI assistant can inspect active pricing, calculate equalized foreign currency values, preview the exact JSON:API mutation, and stage the schedule for human confirmation in the Desktop Approval Center.
The Primary Future Price Scheduling Prompt
Use this prompt with your AI coding assistant (Cursor, Claude Code, Windsurf, or Roo Code) connected to FlightDeck to inspect your current schedule and stage a future price modification:
Inspect the current price schedule for my app [Your App Name]. Show me the current base price and any already scheduled future price changes. I want to schedule a promotional discount to $1.99 starting on [YYYY-MM-DD] and returning to $4.99 on [YYYY-MM-DD]. Stage this price schedule change and show me the full preview before execution.
Modern App Store Pricing Architecture
To configure price schedules effectively, developers must understand how Apple's pricing system evolved in 2023:
1. From "Tiers" to Over 900 Price Points
Historically, Apple enforced rigid pricing tiers (Tier 1 = \$0.99, Tier 2 = \$1.99, Tier 3 = \$2.99). Today, the App Store features over 900 price points (with 700 standard points and 200 custom increments upon request). Prices can be configured with standard rounding conventions (e.g. ending in .99, .00, .50, or territory-specific formats like ¥100 or €0.99).
2. The Base Territory Anchor
Every AppPriceSchedule is anchored to a Base Territory (typically USA or the developer's home country). When you set a base price point in US Dollars, Apple automatically generates equalized prices across 175 storefronts and 45 currencies based on current foreign exchange rates and local value-added taxes (VAT). You retain the option to manually override specific foreign storefronts if you prefer custom regional pricing.
3. Price Invariants & Propagation
- Contiguous Schedule Sequence: An
endDateon anappPricesobject does not automatically restore a previous price on its own. Apple's price scheduling architecture requires declaring a contiguous chronological sequence of price entries. To run a temporary promotion and return to regular pricing, the schedule must include a subsequentappPricesobject whosestartDatematches the promotionalendDateand whose price point specifies the restored standard price. - Propagation and Activation Timing: Apple does not guarantee an instantaneous worldwide cutover at a precise time (such as 00:00:00 UTC). Price schedules take effect on the designated calendar date, and CDN edge propagation across all 175 App Store storefronts typically takes between 1 and several hours. Never advertise a time-sensitive flash sale until you have verified live storefront display.
- Pre-Release Scheduling: You can schedule price changes for unreleased apps; the scheduled pricing will apply the moment the app transitions to
Ready for Sale.
Anatomy of the AppPriceSchedule Resource
In Apple's REST API specification, an AppPriceSchedule is created via POST /v1/appPriceSchedules (appPriceSchedules_createInstance). The request payload bundles the base territory, active prices, and scheduled future prices:
{
"data": {
"type": "appPriceSchedules",
"relationships": {
"app": {
"data": { "type": "apps", "id": "1234567890" }
},
"baseTerritory": {
"data": { "type": "territories", "id": "USA" }
},
"manualPrices": {
"data": [
{ "type": "appPrices", "id": "${price_current}" },
{ "type": "appPrices", "id": "${price_promo}" },
{ "type": "appPrices", "id": "${price_regular}" }
]
}
}
},
"included": [
{
"type": "appPrices",
"id": "${price_current}",
"attributes": {
"startDate": null,
"endDate": "2026-12-01"
},
"relationships": {
"appPricePoint": {
"data": { "type": "appPricePoints", "id": "price_point_id_for_4_99" }
}
}
},
{
"type": "appPrices",
"id": "${price_promo}",
"attributes": {
"startDate": "2026-12-01",
"endDate": "2026-12-15"
},
"relationships": {
"appPricePoint": {
"data": { "type": "appPricePoints", "id": "price_point_id_for_1_99" }
}
}
},
{
"type": "appPrices",
"id": "${price_regular}",
"attributes": {
"startDate": "2026-12-15",
"endDate": null
},
"relationships": {
"appPricePoint": {
"data": { "type": "appPricePoints", "id": "price_point_id_for_4_99" }
}
}
}
]
}
What FlightDeck Can and Cannot Do
To manage pricing safely, observe FlightDeck's architectural boundaries:
What FlightDeck MCP Can Do
- Read Current Pricing: Call
app_price_schedule_getto retrieve active base territory prices, automatic foreign equalizations, and pending future changes. - Set Immediate Base Price: Call
app_price_schedule_setto immediately update an app's base price point in a single verified operation. - Stage Complex Multi-Date Schedules: Use
flightdeck_operation_stagetargetingappPriceSchedules_createInstanceto stage promotional schedules with futurestartDateintervals. - Desktop Approval Center Confirmation: Mutating operations require explicit user approval in FlightDeck Desktop. The UI renders the before-and-after price diffs so you can inspect customer pricing across territories before signing.
- Authoritative Readback: Immediately queries Apple's API post-execution to verify that Apple's servers accepted the scheduled price transitions.
What Apple Enforces Server-Side
- Server-Side Execution: Your computer does not need to stay online. Once Apple receives the schedule, Apple executes the change on the designated
startDate. - Paid Agreement Requirement: Apple rejects
appPriceSchedules_createInstancewith HTTP 403 or 409 if your Paid Applications Agreement is inactive or pending banking info.
Step-by-Step Workflow: Scheduling a Future Price Change
Follow this workflow to configure a scheduled price promotion:
┌────────────────────────────────────────────────────────────────────────┐
│ FUTURE PRICE SCHEDULING WORKFLOW │
│ │
│ 1. QUERY CURRENT APP PRICE SCHEDULE │
│ [Invoke app_price_schedule_get to discover active price point] │
│ │ │
│ ▼ │
│ 2. DISCOVER TARGET PROMOTIONAL PRICE POINT │
│ [Query appPricePoints for base territory USA to find $1.99 ID] │
│ │ │
│ ▼ │
│ 3. STAGE APPRICESCHEDULE MUTATION │
│ [Invoke flightdeck_operation_stage with target startDate/endDate] │
│ │ │
│ ▼ │
│ 4. CONFIRM IN DESKTOP APPROVAL CENTER │
│ [Review price diff in FlightDeck Desktop; click 'Approve Mutation'] │
│ │ │
│ ▼ │
│ 5. DISPATCH & POST-EXECUTION READBACK │
│ [FlightDeck dispatches POST; reads back confirmed future schedule] │
└────────────────────────────────────────────────────────────────────────┘
Step 1: Query Current Pricing
Have your assistant query the app's current schedule:
Check the price schedule for [Your App Name]. What is the current customer price in USA, and are any future price changes currently active?
FlightDeck invokes app_price_schedule_get and returns the base price, active currency code, and scheduled transitions.
Step 2: Stage the Scheduled Promotion
Instruct the assistant to stage the price change:
Stage a future price schedule for [Your App Name] with base territory USA. Set the price to $0.99 starting on 2026-11-25 and ending on 2026-12-02, returning to $2.99 afterward. Do not execute until confirmed.
The assistant resolves the price point IDs, verifies territory equalizations, and stages the mutation via flightdeck_operation_stage.
Step 3: Approve in Desktop Approval Center
- Switch to FlightDeck Desktop.
- In the Desktop Approval Center, review the staged mutation: - Operation:
appPriceSchedules_createInstance- App ID:[YOUR_APP_ID]- Start Date:2026-11-25- Promotional Price:$0.99 - Click Approve Mutation.
- FlightDeck transmits the signed request to Apple and reads back the confirmed schedule.
Paid Apps vs. Auto-Renewable Subscriptions
The rules governing price changes differ significantly depending on the business model:
Paid Apps (Upfront Purchase)
- Changing the price of an upfront paid app affects new purchasers only.
- Existing owners who already purchased the app are unaffected and continue to receive app updates for free.
- No customer consent or notification is required for price increases or decreases.
Auto-Renewable Subscriptions
- Price increases on active subscriptions trigger Apple's Customer Consent & Notification requirements.
- Under Apple policy, price increases generally require notifying subscribers at least 30 days in advance via email and push notification. If the price increase exceeds certain thresholds (e.g., > \$5/month or > 50% increase), the customer must explicitly opt in; failure to opt in automatically cancels the subscription.
- Price Preservation (Grandfathering): When setting subscription price points via
subscriptionPrices_createInstance, developers can set"preserveCurrentPrice": trueto grandfather existing subscribers at their current rate while offering the new price to new customers only.
Common Errors & Troubleshooting
1. 400 BAD_REQUEST: Invalid Start Date
- Cause: Specifying a
startDatein the past, or using a local timezone offset instead of a clean UTC/ISO-8601 date string (YYYY-MM-DD). - Fix: Format dates as
YYYY-MM-DDand ensure the start date is set in the future relative to UTC.
2. 409 CONFLICT: Overlapping Price Intervals
- Cause: Staging multiple
appPricesentities where date ranges intersect or leave undefined temporal gaps. - Fix: Ensure the sequence of
startDateandendDateattributes form a contiguous, non-overlapping chronological timeline.
3. 403 FORBIDDEN_ERROR: Paid Applications Agreement Required
- Cause: Attempting to assign a non-zero price point while the organization only has an active Free Applications Agreement.
- Fix: Have the Account Holder log into App Store Connect and accept the Paid Applications Agreement under Business.
Related Published Guides
- Configuring App Store Price Schedules and Free Tiers
- Managing App Store Territory Availability
- Human-in-the-Loop Governance: The Desktop Approval Center
- Execution vs. Staging Rules: AI Operations Approval
Official References
- App Store Connect Help: Set a Price Schedule
- Apple Developer Documentation: AppPriceSchedules API
- Apple Developer: Upgraded Pricing Capabilities
- Apple Developer: Managing Subscription Price Increases
Evidence Limitations & Verifications
- L1 Official Documentation Verification: Price scheduling structure,
AppPriceScheduleschema, and multi-tier propagation behaviors verified against Apple Developer Documentation and App Store Connect Help. - L2 Codebase Source Inspection: Inspected
/Volumes/ext1/code/asc_mcp/packages/asc_domain/lib/src/services/app_price_schedule_service.dartandSetAppPriceScheduleCommandto verifyappPriceSchedules_createInstancepayload architecture and required human desktop approval. - Read-Back Requirement: FlightDeck's service enforces immediate read-back verification against
apps_appPriceSchedule_getToOneRelatedto confirm Apple server acceptance. - Propagation Reality: Price schedule execution is scheduled on Apple's infrastructure; actual worldwide CDN edge storefront display takes between 1 and several hours from the scheduled execution date.