App Store billing
App Store billing verifies purchases for product access. Establish the customer session through a supported identity provider before uploading a purchase. The App Store authentication setting is not an identity-token adapter for client.session.establish(); StoreKit transaction data belongs in the billing upload below, not in getIdentityToken. This is also separate from importing a ChatGPT, Grok or Claude subscription.
Configure the project
Open Projects → your project → General → Payments → App Store Connect and supply:
| Field | Purpose |
|---|---|
| Bundle ID | The application whose purchases Modem should verify |
| Issuer ID | Your App Store Connect issuer identifier |
| Private key ID | The identifier for the configured server API signing key |
| Private key | The corresponding signing key, stored server-side |
| Shared secret | The receipt-validation shared secret used by this integration |
Generate the signing key for the App Store Server API using Apple’s In-App Purchase key instructions ; do not substitute a key for an unrelated Apple API.
Private key and shared-secret fields accept inline or linked 1Password values. Updating an unrelated field retains saved credentials. Keep these secrets out of the app binary and frontend code.
Map each paid Modem product’s SKU to its App Store product identifier. Use Apple’s In-App Purchase documentation to create and test the product on the Apple side. Saving fields in Modem does not create an App Store product or prove that a test purchase is configured correctly.
Configure with the admin SDK
Use the admin client and server-only required() helper from billing automation. The admin key needs projects:write for this project’s mode. Enable App Store independently from Stripe:
const appStore = await admin.externalBillingProviders.enable(projectId, {
type: 'appleAppStore',
configuration: {
appStoreConnect: {
issuerId: required('APP_STORE_ISSUER_ID'),
privateKeyId: required('APP_STORE_PRIVATE_KEY_ID'),
privateKey: required('APP_STORE_PRIVATE_KEY'),
sharedSecret: required('APP_STORE_SHARED_SECRET')
},
fragile_appStoreConnect: {
bundleId: required('APP_STORE_BUNDLE_ID')
}
}
});fragile_appStoreConnect.bundleId is the current public input field for the bundle ID; keep it alongside the signing configuration. This does not configure App Store customer sign-in or create Apple products.
For an existing connection, retrieve its appleAppStore entry from project.billingProviders, then call update() with its id, ISO updatedAt as expectedUpdatedAt, type and full configuration. Preserve unchanged private-key/shared-secret values with explicit credentialSelections on appStoreConnect; response fields are redacted. For vault-backed values, use the complete billing credential-selection shape, including secretReferenceLabel, under the corresponding private-key or shared-secret selection. To remove it, use disconnect() with the latest revision. The shared update/disconnect workflow explains those methods; Stripe-specific webhook and account transition behavior does not apply to App Store configuration.
Import purchase data
The Client API accepts purchase uploads at:
POST /api/client/projects/{projectId}/customers/{customerId}/upload-receiptAuthenticate as that Modem customer. Send one purchase form per request. If several are supplied, the current importer uses the signed StoreKit transaction first, then the StoreKit 1 receipt, then consumable IDs:
| Field | Value |
|---|---|
storeKitReceiptV2 | A signed StoreKit transaction string |
storeKitReceipt | An object with nonempty receipt and device strings |
consumableStoreKitTransactionIds | A nonempty array of transaction-ID strings |
For StoreKit 2:
{
"storeKitReceiptV2": "SIGNED_STOREKIT_TRANSACTION"
}For a StoreKit 1 receipt:
{
"storeKitReceipt": {
"receipt": "BASE64_RECEIPT",
"device": "DEVICE_IDENTIFIER"
}
}For redeemed consumables whose transaction IDs your app retained:
{
"consumableStoreKitTransactionIds": ["TRANSACTION_ID"]
}Use a real verified transaction from the purchase flow in place of the placeholder. Apple’s transaction APIs expose signed transaction information; see Transaction for the native flow. Do not treat client-provided product IDs or a successful payment screen as verification.
The high-level JavaScript CustomerClient does not expose a receipts resource. Use the Client API directly or its low-level CustomerApiService.uploadReceipt; see HTTP API access for customer authorization and error conventions.
The response is an array of Modem purchase records, which can be empty. Each record contains its Modem id, customerId and productId, the appStoreTransactionId, source: 'appStore', sandboxMode, ISO timestamp strings createdAt and updatedAt, and the tombstoned and nullable tombstonedAt fields. productId identifies the Modem product; it is not Apple’s SKU. The response does not include Apple’s signed transaction payload or populated customer/product objects. After import, reload the customer’s current product and usage state to display access.
Associate the purchase with the customer
Set StoreKit’s appAccountToken to the Modem customer UUID when purchasing. With StoreKit 1, use the same UUID as applicationUsername, which Apple carries into appAccountToken. Reuse that customer’s identity during restore/import. Modem filters transaction history by an exact appAccountToken match; transactions with no token or another customer’s token are not assigned to whoever uploads the receipt.
The authenticated URL customer must match the Modem access token. Verification also checks the configured bundle ID and the project’s environment: Sandbox uses Apple’s Sandbox, and Live uses Production. A valid Apple signature alone is insufficient if app, environment or customer does not match.
For StoreKit 1 and signed-transaction uploads, Modem follows the verified transaction’s history. Consumable IDs are looked up and verified individually. An Apple account can contain purchases belonging to different app users, so do not assume its entire history belongs to the currently signed-in Modem customer.
Access and recovery
Modem verifies imported purchases against the configured application and product mapping before granting access. Expired grants retire their allowances; default-product access applies when no active grant remains. Preserve transaction identifiers in your purchase integration so an interrupted import can be diagnosed without buying again.
On restore, upload the existing verified transaction or receipt as the same customer and reload product/usage state. Repeated uploads converge on stored transactions; they do not refill spent allowances or reactivate a completed/refunded imported grant. Newer transaction state in the same original-transaction lineage can supersede earlier grants; revoked, upgraded-away or expired transactions do not establish current paid access. Keep product SKU mappings correct before diagnosing an import as a missing purchase.
Stripe refund/cancel controls do not manage Apple billing. Use the appropriate Apple workflow for those operations. This receipt-upload integration also does not imply that every App Store Server Notification is ingested automatically: your app must supply the purchase data required by its supported flow.