Regions & Storefronts

How OnsideKit resolves the user's region and storefront before and after login, and how that affects product availability and pricing.

Product availability and pricing vary by region. OnsideKit resolves a region for every products request and exposes the authenticated region as the storefront.

How the region is resolved

When logged in

The region is the account's region — the most accurate source of truth. It is exposed as Onside.defaultPaymentQueue().storefront?.countryCode. Once the user is logged in, this always wins; a pre-login hint (below) is ignored.

When logged out

OnsideKit estimates the region:

1. The onsideDefaultCountryCodeAssumption() delegate hint, if you provide one.

2. Otherwise, the device's system region.

extension AppDelegate: OnsideDelegate {
    func onsideDefaultCountryCodeAssumption() -> String? {
        // An ISO 3166-1 alpha-2 code, e.g. "US", "DE", "GB".
        return userKnownRegion   // or nil to fall back to the device region
    }
}

onsideDefaultCountryCodeAssumption() is the only hook that influences the region, and only before login. Provide it when your app already knows the user's likely region (from their profile or settings) so logged-out pricing is accurate. See The Onside Delegate.

The storefront

struct OnsideStorefront {
    var id: String
    var countryCode: String
}

Onside.defaultPaymentQueue().storefront is nil until the user logs in, then reflects the account's region. It changes when the user logs in or out, or their region changes.

Best practice: fetch before login, then re-fetch

You can and should fetch products before the user authenticates, so your store UI is ready immediately. Because the true region is only known after login, re-fetch your products whenever the storefront changes.

Observe the storefront with a transaction observer:

func onsidePaymentQueueDidChangeStorefront(_ queue: OnsidePaymentQueue) {
    // The region may have changed — refresh prices/availability.
    reloadProducts()
}

See Authentication & User Account for the full observer setup.

Purchase protection on region change

If a user starts a purchase for a product fetched in one region but their account turns out to be in another, OnsideKit does not silently charge the new price. The queued purchase is gated so you can confirm the change with the user or cancel it. This is handled by the payment queue delegate — see Handling Storefront & Price Changes.