BILLING_AND_LIMITS.mdverified at v4.4, quota matrix re-verified at v5.3View source

Docs/BILLING_AND_LIMITS.md — verified at v4.4, quota matrix re-verified at v5.3

Documentation status: Verified for OpenIntelligence v4.4 on 2026-06-30. Product identifiers and the Document Pack status re-checked against source on 2026-08-05. The §2 quota matrix was re-read against source on 2026-09-20 and every figure matches; the grandfathering rule in §4 changed for 5.5 on 2026-09-29 (only a Lifetime purchase, or a subscription begun before 2026-09-30, earns permanent protection), and §4 gives the lines; until 2026-09-29 this line said §4 was not re-verified. Shipped and in-development versions are not restated here: Docs/SHIPPED_VERSION.json is the per-platform record, because a version written into this header goes stale with each release. Corrected 2026-09-29; from 2026-09-22 this line said 5.3 was shipped and 5.4 open, which stopped being true when 5.4 went live on both platforms on 2026-09-24. [evidence_level: artifact_derived, confidence: high, evidence_source: Docs/SHIPPED_VERSION.json (app_store 5.4, preparing 5.5, updated 2026-09-28; its 2026-09-24 note records both platforms READY_FOR_SALE); git blame of this line (8378a3e, 2026-09-22)] Document Pack Add-On is no longer sold (see §3). doc_pack_addon is absent from OpenIntelligence/Resources/StoreKit/StoreKitConfiguration.storekit and has no paywall UI. The BillingProduct.documentPackAddOn case, the cap logic, and the legacyDocumentPackOwner protection state are deliberately retained so existing owners keep their capacity. StoreKitBillingService still requests the id via BillingProduct.allCases, and StoreKit simply omits an unavailable product from the result, so nothing fails. [evidence_level: code_verified, confidence: exact, evidence_source: StoreKitConfiguration.storekit, BillingProduct.swift, PlanUpgradeSheet.swift, StoreKitBillingService.swift:42] Source of truth: The code. The codebase audit this line used to cite, in Docs/AUDIT/, is not in the repository (Docs/AUDIT/ is gitignored).

This document describes the billing tiers, StoreKit 2 product identifiers, and resource quota boundaries as audited in the OpenIntelligence v4.4 codebase.


Correction, 2026-09-22. The free tier’s three Maximum runs a day were documented and displayed but never consumed: the store’s consumeIfAllowed had no caller from 2026-05-12 until 5.4. From 5.4, ChatScreen.sendMessage spends a run before dispatch and the blocked state shows the existing dialog. Every figure in the matrix below was true as a limit and false as an enforcement for that period. [evidence_level: test_verified, confidence: exact]

1. Product Identifier Register

These StoreKit product IDs are defined centrally in BillingProduct.swift:

Product IdentifierrawValueKindAssociated TierDescription
Pro Monthly"pro_monthly"SubscriptionProGrants monthly access to Pro features.
Pro Annual"pro_annual"SubscriptionProGrants annual access to Pro features.
Lifetime (reference name Lifetime Cohort)"lifetime_cohort"Non-ConsumableLifetimeOne-time purchase for permanent Lifetime access. Customers see “Lifetime” from 5.5 (2026-09-29); the product identifier is unchanged.
Document Pack Add-On"doc_pack_addon"ConsumableNoneDiscontinued — not sold. Granted 10 extra document slots per pack. Enum case and entitlement logic retained for existing owners only.

2. Resource Quotas & Limits

Enforcement logic is defined in QuotaPolicy.swift and checked in EntitlementStore.swift at runtime before document ingestion or library creation.

Quota Matrix by Tier

Feature / ResourceFree TierPro TierLifetime Tier
Document Limit5 documents1,000 documentsUnlimited
Library Limit1 library10 libraries20 libraries
Conversations in each library520Unlimited
Maximum Mode Runs3 per day (Metered)UnlimitedUnlimited
Standard Mode RunsUnlimitedUnlimitedUnlimited
Deep Think RunsUnlimitedUnlimitedUnlimited
Private Cloud ComputeAvailable, consent-gated, on iOS/macOS 27SameSame
iCloud SyncNoYesYes
Watched folders, adding one (from 5.8)NoYesYes
Watched folders, stopping oneYes, whatever the planYesYes

Every row is read directly from QuotaPolicy.swift, and the Maximum-mode row from the snapshot builder in EntitlementStore.swift, which grants .unlimited to any tier other than .free and .meteredDaily(QuotaPolicy.freeMaximumModeDailyLimit) to Free. Pro is a 1,000-document, 10-library tier, not an unlimited one; only Lifetime carries unlimited documents, and its library ceiling is 20. [evidence_level: code_verified, confidence: exact, evidence_source: QuotaPolicy.swift freeDocumentLimit=5, proDocumentLimit=1_000, lifetimeDocumentLimit=.max, freeLibraryLimit=1, proLibraryLimit=10, lifetimeLibraryLimit=20, freeMaximumModeDailyLimit=3; EntitlementStore.buildSnapshot; read 2026-09-20]

What the limits count (5.8)

The document limit counts the person’s own documents and the library limit their own libraries (RAGService.countedDocumentCount, ContainerService.countedLibraryCount). Neither counts the guide library (ContainerService.ensureGuideLibrary, “OpenIntelligence Guide”, on the device only), where the app’s three guides are imported from 5.8, nor the guides themselves wherever an earlier version imported them (SampleDocumentManager.isGuide). Through 5.7 the guides went into General and, though their import skipped the limit check, counted afterwards, so a free plan had two documents left. Anything the person adds while the guide library is open goes to their first own library, which is opened. A deleted document frees its place, as before: a count that never fell was judged a worse first impression than people rotating five documents (the owner, 2026-11-03). [evidence_level: test_verified (GuideLibraryTests), confidence: high]

What each plan advertises, and the rule behind it

Rewritten 2026-09-18, after ninety days of App Store Connect data (~/ASC) showed that the buyers are people who decide within two days of download and that Lifetime carries 73% of proceeds on 29% of purchases, while the paywall’s bullets sold storage (“up to 1,000 documents”, “10 libraries”, “expanded workspace limits”) and said nothing about the model.

The rule: a plan bullet may name only what that plan gates. Deep Think and Private Cloud Compute are free-tier features (the table above), so they may not appear as Pro benefits; they appear in the sheet’s story slides as what every plan includes. The one model feature a paid plan gates is Maximum mode, which is QuotaPolicy.freeMaximumModeDailyLimit runs a day on Free and uncapped on Pro and Lifetime, so that is the first bullet of every paid plan. Capacity follows it. Prices are never hardcoded in a tagline, because each storefront has its own and displayPrice is the source.

[evidence_level: code_verified, confidence: exact, evidence_source: PlanUpgradeSheet.swift planOptions and storySlides; QuotaPolicy.swift; EntitlementStore.swift maximumModePolicy; ~/ASC store_purchases and sub_state_analytics through 2026-09-14]

What the plans screen lists (5.8)

Added 2026-11-02. The bullets and the “What you get” list are in PlanBenefits.swift, built from QuotaPolicy, and PlanBenefitsTests holds them to the rule above. Watched folders are gated, so they are listed: a lapsed plan stops the checks and everything imported stays. iCloud Sync is gated too (hasICloudSyncAccess, ContainerSettingsSheet.swift) and is deliberately not listed yet: roadmap row 3ca49a74d54f8103b69be921f0335171, which records real data loss from sync, closes only when the iPhone and the Mac use one library through a session and the conflict-copy count doesn’t grow. The baseline read off the owner’s phone on 2026-11-02 is 519 conflict copies. Until that passes, the app doesn’t advertise sync harder. testICloudSyncWaitsForTheTwoDeviceCheck fails on the day the bullet is added, as a reminder to confirm it.

[evidence_level: code_verified, confidence: exact, evidence_source: PlanBenefits.swift; phone trace 2026-11-01 11:16]

Where the plans screen opens from on a Mac (2026-11-14). PlanUpgradeSheet is presented by the Settings list (SettingsView.body). On macOS a pushed Settings page replaces the list, so View Plans on Plan & Usage, and the upgrade buttons on Intelligence Mode and Libraries & iCloud, did nothing there. Each Settings page presents the sheet itself on macOS (detailScroll in SettingsView+List.swift), and the sheet has a Mac size. Seen on the owner’s Mac before and after. [evidence_level: measured, macOS 27]

The side-by-side table (2026-11-14). Under the three cards the screen now prints “Free, Pro and Lifetime”: one row for each thing a paid plan changes, with what each plan has of it, the buyer’s own plan marked “(yours)” (PlanBenefits.comparison, PlanUpgradeSheet.planComparisonSection). Five rows: Maximum mode, documents, libraries, conversations in each library, watched folders. The conversation limit (QuotaPolicy.evidenceThreadLimit: 5 on Free, 20 on Pro, unlimited on Lifetime, checked in RAGService+ChatHistory.swift) had been gated since before 5.8 and appeared on no screen, in no bullet and not in the matrix above; it is now a bullet on every paid card too, in the Terms’ plan list and in the App Store description, with watched folders beside it. iCloud Sync stays out of the table for the reason above. testTheComparisonListsEveryPaidGate holds the rows to QuotaPolicy. [evidence_level: code_verified, confidence: exact, evidence_source: PlanBenefits.swift, QuotaPolicy.swift; not yet built or run]

What the screen holds, and how it is reached (2026-11-15). The Plan & Usage row in Settings, and the Plan block of the Settings list’s top panel, open the plans screen in one tap; the Plan & Usage page is gone and its usage panel (documents, libraries, chats in the open library, Maximum left today) opens the screen, from counts Settings passes (PlanUsage); opened from anywhere else the panel states the plan’s limits. In order: the reason it opened (not from Settings), the panel, the launch sale as one caption line when LaunchSale confirms one, the three plan cards with their live prices, bullets and buy buttons, the “Free, Pro and Lifetime” table, then restore, manage subscription and redeem a code as links, the store rating (the privacy label moved under the panel the same day, below), the auto-renewal terms and the EULA and privacy links. Removed: the hero, the sale and social-proof banners, the “What you get” list (PlanBenefits.highlights), the three-slide carousel and the “Built for personal research” tip; the cards and the table said the same. The entry points that open the sheet elsewhere (limits, Maximum running out, watched folders, the sale banner, onboarding) are unchanged, each with its PlanUpgradeEntryPoint. On a Mac the Settings pages still present the sheet themselves (detailScroll), now for the upgrade buttons on Intelligence Mode and Libraries & iCloud. [evidence_level: measured, iOS 27 Simulator screenshots; build_verified, macOS]

Order, privacy line and the success haptic (2026-11-15). The cards run Pro (Annual), Pro (Monthly), Lifetime (planOptions), so the one filled button, Annual’s, is the first plan; until then Monthly came first. The line “App Store privacy label: Data Not Collected” sits directly under the “Your plan” panel as one caption, not in the footer; the store rating stays in the footer. A purchase that returns a transaction (BillingService.purchase is nil for pending and cancelled), and a restore that leaves a paid effectiveTier, add one to completedPurchases, which drives DSHaptics.success() from .onChange on the sheet (it was .sensoryFeedback(.success, trigger:) until 2026-11-16, moved so the X-Ray’s Taptic Engine counts it): one haptic, with the panel’s figures changing at the same moment. EntitlementStore is read, not changed. [evidence_level: code_verified, confidence: exact, evidence_source: PlanUpgradeSheet.swift; order and privacy line measured in iOS 27 Simulator screenshots; the haptic was not felt, since the Simulator plays none and no purchase was made]

What each plan says against the others (5.5)

Added 2026-09-29, with the prices that take effect on 2026-09-30 and 2026-10-01. Each card compares itself with the others in the customer’s own currency, from StoreKit’s live prices, and says nothing until both products it compares have loaded in one currency; the US fallback prices never feed a comparison.

CardLabel beside the nameUnder the price
Pro (Monthly)Month to monthnothing; it is what the others are measured against
Pro (Annual)none“Save N% vs Monthly”, N rounded down (58 at $4.99 and $24.99, 57 in Mexico); “$X a month, billed yearly”, rounded up in the currency’s smallest unit ($2.09, ¥334)
LifetimePay once“Less than a year of Monthly” when its price is below twelve Monthly payments; “Pays for itself against Pro Annual in N months”

Everything computed sits below the billed price and is smaller than it. Apple: “the amount that will be billed must be the most prominent pricing element in the layout”, and a per-month breakdown or a saving against another plan “should be displayed in a subordinate position and size to the annual price”. The arithmetic is PlanPriceComparison, pinned by PlanPriceComparisonTests.

Win-back offers are not shown on this screen. Showing and charging them there needs StoreKitBillingService.swift, which this route forbids without the owner naming it, and on 2026-09-29 he chose to leave it: StoreKit shows its own win-back sheet in the iPhone and iPad app by default when the App Store sends a win-back message (Message is unavailable on macOS), and the offers can be redeemed in the App Store and in Subscription settings on every platform. [evidence_level: code_verified, confidence: exact, evidence_source: PlanUpgradeSheet.swift dealBadge(for:), comparisons(for:), livePrices; PlanPriceComparison.swift; https://developer.apple.com/app-store/subscriptions/ "Billing amount" and https://developer.apple.com/documentation/storekit/supporting-win-back-offers-in-your-app, both fetched 2026-09-29; StoreKit.swiftinterface in the macOS 27 SDK, Message marked unavailable on macOS]

Readable at every text size (5.7)

Added 2026-10-16, from Apple’s accessibility audit and the screenshots of the plans sheet in light and dark at the default and the largest text sizes. The subheading under the headline is in the readable gray (DSColors.secondaryText, 5.23 to 1 measured, was 3.48); the privacy-label banner’s words are in the label color with the purple kept in its icons (gray on its purple tint measured 3.34 to 1); each story slide’s second line is in the label color on its tint; and the title is inline at accessibility sizes, where the large title was cut to “Workspace…”. Prices, labels and comparisons are unchanged. [evidence_level: measured (iOS 27.0 Simulator, BenchmarkRuns/2026-10-16-accessibility-pass-3/), confidence: high, evidence_source: PlanUpgradeSheet.swift heroSection, socialProofBanner, storySlides]


3. Document Pack Add-On Mechanics (discontinued product, retained for existing owners)

The pack was withdrawn from sale in v4.4. Nothing below describes a purchase a new user can make; it describes how the app continues to honour packs bought before the withdrawal. Read every “purchase” below as “a historical purchase being re-validated.”

  • Allowance: A "doc_pack_addon" transaction appends a ledger entry containing 10 credits to documentPacks.
  • Enforcement Cap: Users are capped at a maximum of 3 active document packs simultaneously (yielding a maximum bonus of +30 documents). The property hasReachedDocumentPackCap in EntitlementStore.swift gates purchases if addOnPacks >= 3.
  • Expiration: Consumable packs are verified against transaction expiration dates. Expired packs are pruned on app launch via pruneExpiredDocumentPacksIfNeeded().

4. Entitlement Reconciliation & Legacy Protection

  • Grandfathering Protection: A sticky paid-history protection state (LegacyProtectionState) resolves the effective tier to Lifetime whatever the current StoreKit tier (EntitlementStore.swift:205, :267). Changed for 5.5 on 2026-09-29. Only two things earn .historicalPaidPurchase now, through EntitlementStore.protectionEarned(by:originalPurchaseDate:isRevoked:) (:242): a Lifetime purchase (lifetime_cohort), and a Pro subscription whose original purchase date is before 2026-09-30 00:00 UTC (subscriptionProtectionCutoff, :235). A subscription that begins later gives Pro while it is active and nothing permanent, and a refunded transaction earns nothing. The launch reconcile (EntitlementStore.swift), the StoreKit history scan for a new device or reinstall (:461) and each purchase or restore (:595) all apply that one rule. Protection already stored on a device is never lowered.
    • Why the cutoff: through 5.4 every paid purchase earned the protection, a free trial included, so a month of Pro, or a trial that never converted, became Lifetime for good. The owner decided on 2026-09-29 that people who got it that way keep it; see Docs/ai/DECISIONS.md, 2026-09-29. Whether a subscription that lapses and is bought again keeps its first original purchase date is not verified; Apple documents that originalID stays the same across renewals and restores.
    • Still true: .legacyDocumentPackOwner, for owners of the discontinued Document Pack (§3), also resolves to Lifetime; a refund does not clear protection that was already stored (handleRevocation, :620). [evidence_level: code_verified, confidence: exact, evidence_source: EntitlementStore.swift:205, 235, 242-258, 267, 404-445, 461-484, 595-610, 620; MonetizationPolicy.swift:22-27; EntitlementProtectionTests (8 tests); Transaction.originalPurchaseDate in the Xcode 27 iOS StoreKit swiftinterface; developer.apple.com/documentation/storekit/transaction/originalid, read 2026-09-29]
  • Screens read the effective tier (5.8, 2026-11-04). effectiveTier is the tier with protection counted; activeTier is only what StoreKit sells now. The plans sheet (PlanUpgradeSheet) read activeTier for “Current plan”, each plan card’s already-unlocked state and its analytics, so a protected person (the owner’s iPhone) saw “Current plan: Free” and was offered Pro and Lifetime while Plan & Usage said Lifetime. All three read effectiveTier now. Settings reads activeTier only to say why the tier is Lifetime (“Grandfathered from prior purchase”). [evidence_level: code_verified, confidence: high, evidence_source: PlanUpgradeSheet.swift; SettingsView.swift subscriptionStatusText]
  • Local Simulation: In DEBUG builds, on a device as well as in the simulator, the app supports simulated billing overrides using simulateDebugPurchase(_:) to bypass StoreKit connection failures (corrected 2026-09-29: this said simulator builds; the gate is #if DEBUG alone, EntitlementStore.swift:492-553).

5. Promotional pricing and the launch sale

Added 2026-09-09.

Where a sale is announced, and where it is not

Three places, all reading the same LaunchSale.offer, which returns nothing unless StoreKit’s live price is genuinely below the recorded regular price in the customer’s currency and the date is inside the window: the plans sheet (since 5.2), the LaunchSaleBanner at the top of the Chat and Documents tabs for the free tier (5.3), and the App Store promotional text, which is set by API on the live version and is the only one of the three that a human has to take down when the sale ends; the metadata history carries the text to restore. No countdown, no “only N left”, no pre-selected plan: the discount is real and the copy says the real number and the real last day.

The Lifetime card also states its price in months of Pro Annual (LaunchSale.monthsOfAnnual, 2026-09-18): StoreKit’s live prices for the customer’s storefront, never the hardcoded US fallbacks, rounded down, nil until both products have loaded. At the sale price ($39.99 against $29.99) that reads 16 months; on 2026-09-30 ($49.99 against $29.99), 20; from 2026-10-01 ($49.99 against $24.99), 24. It is the comparison a buyer is already making, done with the store’s own numbers.

Regular prices, as App Store Connect holds them

Only the USA price is set by hand. Apple generates the other 174 storefronts from it, and those generated figures are what customers actually pay, so they are read from the API rather than converted.

Changed 2026-09-30. The owner set the standing Lifetime price to $49.99 on 2026-09-29, effective the day the launch sale ended, so the price went from the $39.99 sale straight to $49.99. It was $59.99 before the sale (59.99 GBP, 69.99 EUR, 79.99 CAD, 99.99 AUD, 5900 INR, 10000 JPY, 399.90 BRL, 1299 MXN). The Lifetime column below is Apple’s equalization of the $49.99 price point, read before the write; Pro Annual is unchanged. The schedule written was [null to 2026-09-30] 39.99 and [2026-09-30 to null] 49.99, read back identical, and the schedule it replaced is .sale-snapshots/20260929T192514Z-pre-lifetime-4999.json (scripts/schedule_sale.py --restore <that file> --confirm undoes it). Before the next sale, set REGULAR_PRICE in scripts/schedule_sale.py and LaunchSale.regularLifetimePrices to these prices; the script refuses to write while its constant says 59.99, and the single-amount-per-currency property below has not been re-checked for the new price point. Done 2026-09-29 for 5.5: both now hold these prices (REGULAR_PRICE = 49.99), and scripts/verify_sale_prices.py reported every recorded currency matching the schedule’s open-ended $49.99 interval, with no currency carrying two prices across the 28 territories it checks. That was not enough. Read across all 175 territories the same day, the $49.99 point does not resolve to one price per currency: USD is 49.99 in 87 territories and 59.99 in 22 (ALB ARM AZE BEN BLR BRB CIV CMR COG GEO GHA ISL KEN MAR MDA MUS NPL SEN UGA UKR ZMB ZWE), and EUR is 59.99 in 24 and 49.99 in one (MNE). LaunchSale keys by currency, so in a future sale window Montenegro would be told its regular EUR 49.99 was reduced from EUR 59.99. No build is exposed, because the only window closed on 2026-09-30 and a new sale needs a new build. Before the next sale, key the table by territory or leave USD and EUR out, and make scripts/verify_sale_prices.py read every territory rather than its 28. Done for 5.7 (2026-10-17): LaunchSale.regularLifetimePriceExceptions holds those 23 territories with the currency each was read in, and regularLifetimePrice(currency:territory:) gives a listed territory its own price, any other its currency’s, and USD or EUR nothing until the storefront’s country is known (StorefrontTerritory, read from Storefront.current when the app comes to the front and when the plans screen opens). scripts/verify_sale_prices.py reads every territory’s currency from /v1/territories and compares each open-ended price with what the app would show there; its first run, on 2026-10-17, found 175 territories, 141 matching, 34 with no recorded price (no banner there) and 0 that differ. [evidence_level: test_verified (LaunchSaleTests), confidence: high for the table, medium for the storefront read, which no sale has exercised; evidence_source: LaunchSale.swift] [evidence_level: measured, confidence: exact, evidence_source: open-ended rows of /v1/inAppPurchasePriceSchedules/6756638872/automaticPrices and manualPrices, 175 territories, grouped by /v1/territories currency, 2026-09-29] [evidence_level: measured, confidence: exact, evidence_source: POST /v1/inAppPurchasePriceSchedules and GET .../manualPrices, 2026-09-29 12:25 PT; /v1/inAppPurchasePricePoints/<49.99 USA>/equalizations]

Changed 2026-10-01, subscriptions. On 2026-09-29 the owner scheduled Pro Annual at $24.99 (was $29.99) and Pro Monthly at $4.99 (was $5.99) from 2026-10-01, in App Store Connect’s price editor, which recalculated every storefront from the US price: Annual goes down in 161 storefronts and Monthly in 166, none goes up, and the rest keep their current price. Existing subscribers renew at the lower price; Apple offers no way to preserve a higher one. The columns below are the scheduled 2026-10-01 prices read back from the API. At these prices Annual is 5.0 times Monthly, as before, so the saving stays 58% where both prices moved together. Through 5.4 the paywall hardcoded that figure as a bullet; from 5.5 it is computed per storefront (§2, “What each plan says against the others”). The local StoreKitConfiguration.storekit, which only Xcode and the simulator read, carries the same US prices from 2026-09-29 at the owner’s word: $4.99, $24.99 and $49.99, Lifetime named “Lifetime”, the product descriptions App Store Connect has in review, and no introductory offer (App Store Connect lists none on either subscription, read the same day). Loaded in a StoreKit test session on the iOS 27 simulator, it returned exactly those three prices. The annual win-back offer is now $14.99 for the first year (winback_annual_2026_1499, 2026-10-01 to 2027-10-01, every storefront). The $19.99 offer it replaces cannot be ended through the API while live (HTTP 409) and stays until 2027-09-24; App Store Connect states that where offers overlap “the best offer will be shown”. The monthly win-back ($2.99 a month for three months) is unchanged. [evidence_level: measured, confidence: exact, evidence_source: GET /v1/subscriptions/{id}/prices per territory and /v1/subscriptions/6756638919/winBackOffers, read 2026-09-29 after the changes; App Store Connect price-change confirmation screens]

CurrencyLifetimePro AnnualPro Monthly
USD49.9924.994.99
GBP49.9924.994.99
EUR (Germany)59.9929.995.99
CAD69.9934.996.99
AUD79.9939.997.99
INR49992499499
JPY80004000800
BRL299.90149.9029.90
MXN99949999

For the $59.99 schedule (corrected 2026-09-29: not for the $49.99 one, see above): across all 177 generated Lifetime territory prices, every currency resolves to exactly one amount, which is what makes LaunchSale safe to key by currency rather than territory. That is a property of this price schedule and not a guarantee from Apple, so scripts/verify_sale_prices.py re-checks it and reports drift. [evidence_level: measured, confidence: exact, evidence_source: /v1/inAppPurchasePriceSchedules/6756638872/automaticPrices (177 rows) and /v1/subscriptions/6756638919/prices (175 rows), grouped by currency, read 2026-09-09]

US proceeds are a flat 85% of list under the Small Business Program, which the price point records show directly. The blended net across all territories is lower, 66.4%, because several storefronts quote VAT-inclusive prices that Apple remits. Use 66.4% for revenue forecasts and 85% only for US-only questions. [evidence_level: measured, confidence: exact, evidence_source: proceeds field on USA price points (85%); SUM(proceeds_usd)/SUM(sales_usd) over the ten Lifetime rows in store_purchases, ~/ASC/data/asc.sqlite3, 2026-09-09. That archive is not version-controlled, so the figure is reproducible only while it exists.]

How a discount is delivered, and why the app has to announce it

A non-consumable cannot have a “sale” in the App Store sense. The only mechanism is a temporary price change, which App Store Connect accepts with a start and an end date and reverts on its own; the maximum length is one year. [evidence_level: documented, confidence: exact, evidence_source: https://developer.apple.com/help/app-store-connect/manage-in-app-purchases/schedule-price-changes-for-in-app-purchases, fetched 2026-09-09]

The App Store shows no strikethrough, no “was/now” and no sale badge for in-app purchases. A customer during a price change simply sees a smaller number. The discount therefore does not exist as a discount unless the app says so, which is what LaunchSale and the paywall banner are for.

What LaunchSale guarantees, and what it does not

OpenIntelligence/Features/Billing/LaunchSale.swift advertises nothing unless both hold:

  1. now is inside LaunchSale.window.
  2. StoreKit’s reported price is strictly below the regular price recorded for Lifetime in that customer’s currency.

Condition 2 means a price change that was never scheduled, never reached a storefront, or has already reverted produces silence whatever the date says. The percentage comes from the two real numbers, rounded down, so the saving is never overstated, and it is computed per storefront because Apple rounds each territory to its own price point.

The limit, stated plainly. Condition 2 is not “a sale is running”, it is “the price is below a constant compiled into this build”. Apple recalculates generated prices when tax and exchange rates move, so a table recorded today can be wrong in six months and the app would then advertise a discount nobody scheduled. Run scripts/verify_sale_prices.py before every sale. Separately, EntitlementStore caches its products, so PlanUpgradeSheet refreshes them on appear to keep the banner and the checkout price the same number. [evidence_level: code_verified, confidence: high, evidence_source: LaunchSale.swift offer(for:storeProduct:now:), PlanUpgradeSheet.swift .task, OpenIntelligenceTests/Features/Billing/LaunchSaleTests.swift]

Why only Lifetime is ever discounted

Pro Annual and Pro Monthly are deliberately excluded, for two independent reasons.

  • Pro Annual’s 7-day free trial was withdrawn on 2026-09-18. Ninety days of data: five trial starts, one converted to full price, two stuck in billing retry, one churned from the trial; Annual’s proceeds for the period were $25 against Lifetime’s $140. The app stopped advertising the trial that day (PlanUpgradeSheet), and the introductory offer, one per territory in App Store Connect, 175 in all, is removed by the owner (an agent’s deletion was blocked by the harness). Until it is removed, the store’s own purchase sheet still shows the trial; the app under-claims rather than over-claims in the meantime. Existing trialists are unaffected by the removal. Done 2026-09-18: all 175 per-territory offers were deleted through DELETE /v1/subscriptionIntroductoryOffers/{id}, verified by re-listing the subscription’s introductoryOffers and getting zero. Pro Annual now has no introductory offer of any kind, so it could take one again in future; the reason below is why it still takes no sale.
  • A temporary price change on a subscription creates a price increase later. When the price reverts, everyone who subscribed at the sale price faces an increase at renewal. Apple requires consent where a region demands it, where the increase exceeds 50% and about US$50 a year, or where the subscriber saw an increase in the last 12 months, and a subscriber who does not consent has the subscription expire at the end of the current cycle.

Lifetime is a non-consumable, so it reverts with no consequence for anyone who already bought. It is also 83% of revenue, so restricting the sale to it costs almost nothing. [evidence_level: documented+measured, confidence: exact, evidence_source: GET /v1/subscriptions/{id}/introductoryOffers, 0 rows for pro_annual and pro_monthly, 2026-09-29 (the trial was withdrawn 2026-09-18; the local StoreKitConfiguration.storekit carried it until 2026-09-29); https://developer.apple.com/help/app-store-connect/manage-subscriptions/manage-pricing-for-auto-renewable-subscriptions/ and .../set-up-introductory-offers-for-auto-renewable-subscriptions/, fetched 2026-09-09; store_purchases revenue share]

One US price change is a different discount in every storefront

Apple rounds each territory to its own price ladder, so a single USA change from $59.99 to $39.99 does not land at 33% anywhere but the USA and the UK. Read from Apple’s equalizations for the $39.99 USA price point rather than converted:

TerritoryRegularSaleOff
MexicoMX$1299MX$89930%
India₹5900₹399932%
USA, United Kingdom59.9939.9933%
Germany€69.99€44.9935%
CanadaCA$79.99CA$49.9937%
BrazilR$399.90R$249.9037%
Australia, JapanA$99.99, ¥10000A$59.99, ¥600040%

This is why LaunchSale.percentOff computes per storefront from the customer’s own two prices instead of showing a single advertised figure, and why marketing copy that has to be true everywhere says “a third off” rather than a percentage. 30% is the floor across these nine. [evidence_level: measured, confidence: exact, evidence_source: /v1/inAppPurchasePricePoints/<USA 39.99>/equalizations, 174 rows, read 2026-09-09]

Writing the price change: the schedule is replaced, not amended

There is no “add a price change” call. POST /v1/inAppPurchasePriceSchedules submits the entire schedule, and the schedule is not a list of prices, it is a partition of the timeline. Apple enforces that intervals do not intersect, that the timeline is covered with no gaps, and that the rightmost interval has no end date.

A temporary sale is therefore three intervals, because the regular price has to hold both the time before the sale and the time after it:

IntervalPriceRole
null to start59.99open at the start of time
start to end39.99the sale
end to null59.99what it reverts to, open forever

[evidence_level: measured, confidence: exact, evidence_source: two HTTP 409 responses from POST /v1/inAppPurchasePriceSchedules, 2026-09-09. ENTITY_ERROR.INVALID_INTERVAL: "Adjacent intervals must not intersect for USA: [null - null] and [2026-09-15T00:00 - 2026-09-30T00:00]". ENTITY_ERROR.INVALID_END_DATE: "Entire timeline must be covered for USA. Rightmost interval must not have an end date". Apple's reference documents the field names but none of this.]

The consequence for the guard in schedule_sale.py: the price that answers “what is the regular price” is the open-ended interval, not the one with a null start. A sale is already scheduled means the null-start interval is still the regular price but so is the tail, and it is the tail that customers pay once the sale expires.

Two further things the error messages settle, which Apple’s help pages do not. Inline entity ids must be written ${local-id} with literal braces, not as bare strings. And the intervals are half-open: [start, end), since adjacent intervals share a boundary date without intersecting. So the end date is the day the price reverts, and the last day at the sale price is the day before. LaunchSale.deadlineText names that day, which makes the advertised deadline exact rather than approximate. [evidence_level: measured, confidence: high, evidence_source: same two 409 responses; the half-open reading is what makes "must not intersect" and "must be covered" simultaneously satisfiable for adjacent intervals sharing a date, and is confirmed by Apple accepting that shape]

Running a sale

  1. zsh -ic 'python3 scripts/verify_sale_prices.py' and fix any drift it reports.
  2. Set LaunchSale.window before the build, since it compiles into the binary: scripts/schedule_sale.py --start ... --end ... --write-window.
  3. On release day, the same script with --confirm writes the temporary price change.

Step 1 is not optional; it is what keeps the struck-through price honest. schedule_sale.py reads the live schedule first and refuses to write if the standing price is not what this repo expects, or if a hand-set price exists outside the USA, because either would mean the submission silently changes or deletes a real price. The full procedure with exact figures is Docs/Release/5.2/launch-sale.md.

Offer codes, for targeted discounts that leave the list price alone

Offer codes now cover consumables, non-consumables and non-renewing subscriptions, not just auto-renewable ones, and promo codes for in-app purchases were retired on 2026-03-26. Limits: 10 active offers per app, up to 1,000,000 codes per app per quarter, one-time-use batches of 500 to 25,000, custom-code batches up to 25,000 redemptions, a maximum 6-month expiry, and one redemption per customer per offer. An offer can be a discounted price rather than free. [evidence_level: documented, confidence: exact, evidence_source: https://developer.apple.com/help/app-store-connect/manage-in-app-purchases/create-offer-codes-for-in-app-purchases/, fetched 2026-09-09]

Prefer offer codes over a price change for win-back and targeted outreach: they never touch the public price and each redemption is attributable.

Redeeming a code in the app (5.7). The plans sheet has a “Redeem a Code” button under Restore Purchases. It presents Apple’s redemption sheet: offerCodeRedemption(options:isPresented:onCompletion:) on iOS 27 and macOS 27, whose result is the transaction the redemption produced, and the call it replaces on iOS 26 and macOS 26, whose result only says the sheet was shown. Apple’s page for the call says a code is redeemed through that sheet and not through an interface of the app’s own. A redeemed transaction reaches the app through the Transaction.updates listener that purchases already use. On 27, where the transaction is handed back, the sheet also reads the current entitlements again two seconds later; on 26 it re-reads nothing, because a closed sheet says nothing about a redemption. A product identifier outside BillingProduct is dropped by that listener, so a code has to be for one of the app’s own products. [evidence_level: build_verified for the button and sheet, documented for Apple's behaviour; confidence: high; evidence_source: PlanUpgradeSheet.swift, RedeemCodeEntry.swift, RedeemCodeOutcomeTests; developer.apple.com/documentation/swiftui/view/offercoderedemption(options:ispresented:oncompletion:), fetched 2026-10-09; the StoreKit interface in the Xcode 27.0 SDK] No code has been redeemed with it, in the sandbox or anywhere else. RedeemOption, the type of the new call’s options, has no values in the Xcode 27.0 SDK, so the set passed is empty.

6. The privacy policy screen (PrivacyPolicyView, kept under Features/Billing)

Added 2026-10-14, for 5.7; rewritten 2026-10-15. The in-app privacy policy carries the same sections as gunndamental.com/openintelligence/privacy/ (gunzino.me until 2026-11-06). scripts/privacy_policy.py writes both from one text, and with them Gunzino’s hand-written copy of the page, which its deploy compares the built page with (Docs/ai/RUNBOOK.md, “Changing the privacy policy”). Settings, About opens it with a Privacy Policy row. From 2026-05-28 (a666a9b) until then nothing opened it: the Plans screen’s Privacy Policy button became a link to the website, and PlanUpgradeSheet.showingPrivacy is still declared and never set to true. The Plans screen keeps the website link. Nothing about plans, prices or limits changed.

2026-11-16: Settings’ Apple Intelligence and Private Cloud Compute pages became one page, Model & Privacy, so the two places the text names the “When to allow it” setting say “Settings, Model & Privacy” (PrivacyPolicyView and the source text in scripts/privacy_policy.py, edited by hand in both). The script was not run, because it also writes the Gunzino repository’s two copies of the page: until it is run there, the website still says “Settings, Private Cloud Compute”. Nothing else in the policy changed. [evidence_level: code_verified, confidence: high]

2026-11-17: Model & Privacy shows the permission as a row of three buttons under the heading “Private Cloud Compute”, with no “When to allow it” label, so the same two places now say “Settings, Model & Privacy, Private Cloud Compute” (PrivacyPolicyView and scripts/privacy_policy.py, edited by hand; the script was not run, so the Gunzino copies still say the older wording until it is). The three choices keep their names. [evidence_level: code_verified, confidence: high]

Each statement in the text was checked against the code on 2026-10-15:

  • No advertising or tracking code: no AdSupport, AppTrackingTransparency, SKAdNetwork or AdAttributionKit in the app. URLSession is used by WebPageFetchService (an ephemeral session that never accepts or sets cookies), by AppStoreRatingSnapshot, and by AdapterManager, which nothing calls (removed in 5.7 on 2026-10-20); LocalOpenAIServerLLMService.swift is inside #if false.
  • Private Cloud Compute is iOS, iPadOS and macOS 27 only: FoundationModelSessionFactory throws modelUnavailable before 27. Show Details on CloudConsentPromptView gives the reason and the size of what would be sent.
  • When it is used (corrected 2026-10-15): with Hybrid, ModelExecutionPlanner sends an answer whose passages don’t fit (!localBudget.fits) and a Deep Think or Maximum answer drawn from more than one document (complexityRequestsPCC); with the picker’s Private Cloud Compute, every answer. cloudConsentDecision reads no mode, so “Allow without asking” (shown as “Allow for Deep Think and Maximum” through 5.6) allows every request.
  • What differs before 5.7, said in the text: the setting’s name, the search cache, dictation, Spotlight removal, web pages, Siri asking first and crash reports (each found with git log -S against the v5.6.0 tag).
  • iCloud Sync needs Pro or Lifetime (effectiveTier.isAtLeast(.pro)).
  • A web page comes from Save a Web Page, the Link field of Add to Library, or a web address pasted on the Documents screen: the three callers of WebPageFetchService.fetch. From 5.7 (added 2026-10-17) a page shared to the app from another app’s share sheet is a fourth way in, and the policy names it: the share extension only writes the address to the app group’s inbox (SharedInbox), and the app downloads it through the Paste control’s staging (SharedInboxImport, PastedContentStaging.stage), so the callers of fetch are still those three. [evidence_level: code_verified, confidence: high, evidence_source: PastedContentStaging.swift:123, ScreenAwarenessIntents.swift:122, AddToLibraryIntent.swift:77, SharedInboxImport.swift]
  • A crash report (CrashReports.fields) holds the versions, the device model, how the app ended, the app’s two state domains (import and answer) and the call stack, and leaves out an exception’s message and the memory region description. About can email its summary or share the whole file.
  • Dictation is DictationTranscriber, on the device. Turning off Spotlight Indexing calls deleteAllSearchableItems. Deleting a library removes each of its documents, which clears their passages, keyword rows and Spotlight entries (LibraryDeletion).
  • Language data for the Atlas (added 2026-10-17): AtlasLabeling.loadWordClasses calls NLTagger.requestAssets(for:tagScheme:) with a language code and .lexicalClass only, for the eight languages in languagesWithWordClasses that the device lacks, once a launch; nothing from the library goes with it. The policy’s date moved to October 17, 2026 with this paragraph; the gunzino.me copy waits on the owner’s word for that repository.
  • Cached questions and the passages found for them (semantic_query_cache) are deleted from 5.7 once the documents or the app’s version change (RAGService.deleteUnreachableCachedSearches, added 2026-10-15). Through 5.6 nothing deleted them, and they outlived their library. The policy says what each version does.

[evidence_level: code_verified, confidence: high, evidence_source: the files named above, read 2026-10-15; git log -S'showingPrivacy = true' for the button]

7. An action’s engine reads the saved plan (added 2026-10-15, for 5.7)

A Shortcuts or Siri action that runs while the app is closed builds its own engine (IntentSupport.engine) with no entitlement store. Its document check reads EntitlementStore.savedDocumentAllowance, from savedEntitlementSnapshot: the plan, the document packs not yet expired and any legacy protection, as the app’s store last saved them, built by the store’s own buildSnapshot. Until 5.7 that check used QuotaPolicy.documentLimit(), whose default is the free plan, so Add to Library refused a Pro or Lifetime library of five documents or more. The library limit already read the saved plan (currentLibraryLimit). Nothing about prices or limits changed. [evidence_level: test_verified (SavedEntitlementSnapshotTests), confidence: high]

5.7, 2026-10-22. The plan screens (PlanUpgradeSheet, LaunchSaleBanner) took the app-wide visual standard (colour, spacing, corners) with their text sizes unchanged. No price, plan, limit or purchase path changed (ui_wiring_check.py OK). [evidence_level: build_verified, confidence: high]

8. What a development build records about plans (added 2026-11-03)

Debug builds only (VerificationJournal), for closing plan rows from a device’s journal: billing.tier at launch after the purchases are read and on each change (the tier Settings shows, StoreKit’s tier, the legacy protection and the tier before), from ContentView, since EntitlementStore.swift is a hard-boundary file; plan.documentCheck when Add is asked for (what the plan counted, its limit, unlimited or not, allowed or not); plans.redeemCode with the redemption’s case only (redeemed, closed, cancelled, failed), never the failure’s text. [evidence_level: code_verified, confidence: high, evidence_source: ContentView.swift recordBillingTier, DocumentLibraryView.swift presentDocumentPickerOrUpgrade, PlanUpgradeSheet.swift]