What are the subscription renewal states, how do grace period and billing retry differ, and who should keep access?

Predict first

What access does the user have through a payment failure, with and without grace period?

import StoreKit

enum State: String { case subscribed, grace, billingRetry, expired, revoked }
func hasAccess(_ s: State) -> Bool { s == .subscribed || s == .grace }

// renewal-state raw values StoreKit reports (the App Store Server API status uses the same numbers)
let real: [(String, Product.SubscriptionInfo.RenewalState)] = [
    ("subscribed", .subscribed), ("expired", .expired), ("billingRetry", .inBillingRetryPeriod),
    ("grace", .inGracePeriod), ("revoked", .revoked)]
print(real.map { "\($0.0)=\($0.1.rawValue)" }.joined(separator: " "))

enum Event { case renewed, paymentFailed, graceEnded, retryGaveUp, recovered, refunded }
func next(_ s: State, _ e: Event, graceEnabled: Bool) -> State {
    switch (s, e) {
    case (_, .refunded): return .revoked
    case (.subscribed, .paymentFailed), (.grace, .paymentFailed): return graceEnabled ? .grace : .billingRetry
    case (.grace, .graceEnded): return .billingRetry
    case (.billingRetry, .retryGaveUp), (.grace, .retryGaveUp): return .expired
    case (.grace, .recovered), (.billingRetry, .recovered), (.subscribed, .renewed), (.expired, .renewed): return .subscribed
    default: return s
    }
}
for grace in [true, false] {
    var s = State.subscribed
    var trace = ["subscribed"]
    for e in [Event.paymentFailed, .graceEnded, .recovered, .paymentFailed, .graceEnded, .retryGaveUp] {
        s = next(s, e, graceEnabled: grace)
        trace.append("\(s.rawValue)\(hasAccess(s) ? "+" : "-")")
    }
    print("grace period \(grace ? "on " : "off"):", trace.joined(separator: " > "))
}

• grace on: subscribed > grace+ > billingRetry- > subscribed+ > grace+ > billingRetry- > expired-; grace off goes straight to billingRetry-
• access is kept during every failure state
• billing retry keeps access and grace does not