Used by thousands of students worldwide - help us reach 150 members
In-App Purchases
/iapMobile in-app purchase entitlements. Lets the iOS app validate an App Store subscription with Apple and attach it to the signed-in Sharh account, and lets any client read the account's current mobile subscription state.
/iap/subscriptionGet the current user's mobile subscriptionPOST/iap/ios/validateValidate an iOS App Store subscription and link it to the accountGet the current user's mobile subscription
Returns the mobile (App Store) subscription entitlement stored on the authenticated user. `isActive` is true only when the stored entitlement is active and its `expiresAt` is unset or in the future. When the entitlement is not active and `expiresAt` has passed, `status` is reported as `expired`; otherwise the stored status is returned (`none` for users who never validated a purchase). No call to Apple is made; the data reflects the last validation.
Errors
401Plain text `Unauthorized: No token provided`.403Plain text `Forbidden: Invalid token`, or `Forbidden: You do not have the required permissions`.404Plain text `User not found` (the token's user no longer exists).
curl -X GET "https://app.ummahspot.com/iap/subscription" \
-H "Authorization: Bearer $SHARH_TOKEN"{
"subscription": {
"platform": "ios",
"productId": "sharh.monthly.subscription",
"transactionId": "2000000123456789",
"originalTransactionId": "2000000123456000",
"status": "1",
"isActive": true,
"expiresAt": "2026-10-18T14:05:00.000Z",
"environment": "Production",
"lastValidatedAt": "2026-09-18T14:05:12.000Z",
"source": "app_store_server_api"
}
}Validate an iOS App Store subscription and link it to the account
Validates proof of an App Store subscription purchase with Apple and saves the resulting entitlement on the authenticated user. At least one of `transactionReceipt`, `transactionId` or `originalTransactionId` must be sent. When the server is configured for the App Store Server API and a transaction id is supplied, the transaction and its subscription status are fetched from Apple (Production first, then Sandbox); otherwise the `transactionReceipt` is verified through Apple's receipt verification endpoint. The purchase must belong to the Sharh app bundle and to a recognised subscription product (by default `sharh.monthly.subscription` or `sharh.yearly.subscription`). The latest transaction for a recognised product determines the result. An App Store subscription can be linked to only one Sharh account: if another user already holds the same `originalTransactionId`, the request fails with 409. On success the stored entitlement is overwritten and returned in the same shape as `GET /iap/subscription`. `status` is `revoked`, `none` (no matching subscription found), Apple's numeric subscription status as a string (for example `"1"` active, `"4"` billing grace period) on the Server API path, or `active` / `expired` on the receipt path. `source` is `app_store_server_api` or `verify_receipt`. A validation that finds an inactive or expired subscription still returns 200 with `isActive: false`.
Body parameters
transactionReceiptstring | Base64 App Store receipt. Required when no transaction id is sent, or when the server is not configured for the App Store Server API. |
transactionIdstring | StoreKit transaction id of the purchase. |
originalTransactionIdstring | StoreKit original transaction id identifying the subscription. |
productIdstring | Product id of the purchase. When sent, it must be one of the recognised subscription product ids. |
Errors
400JSON `{ "error": "<code>", "message": "..." }`. Codes: `missing_purchase_proof` (none of transactionReceipt, transactionId, originalTransactionId sent), `IAP_PRODUCT_NOT_ALLOWED` (unrecognised product id), `IAP_BUNDLE_MISMATCH` (purchase belongs to a different app), `IAP_TRANSACTION_NOT_FOUND` (Apple does not know the transaction), `IAP_RECEIPT_INVALID` (Apple rejected the receipt).401Plain text `Unauthorized: No token provided`.403Plain text `Forbidden: Invalid token`, or `Forbidden: You do not have the required permissions`.409JSON with `error: "subscription_already_linked"`: this App Store subscription is already linked to another Sharh account.500JSON `{ "error": "...", "message": "..." }` for unexpected failures (for example Apple being unreachable). `error` defaults to `iap_validation_failed` when the underlying error carries no code.503JSON with `error: "IAP_SHARED_SECRET_MISSING"` or `"IAP_VALIDATION_NOT_CONFIGURED"` when the server lacks the Apple credentials needed for the supplied proof.
curl -X POST "https://app.ummahspot.com/iap/ios/validate" \
-H "Authorization: Bearer $SHARH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"transactionReceipt":"string"}'{
"subscription": {
"platform": "ios",
"productId": "sharh.monthly.subscription",
"transactionId": "2000000123456789",
"originalTransactionId": "2000000123456000",
"status": "1",
"isActive": true,
"expiresAt": "2026-10-18T14:05:00.000Z",
"environment": "Production",
"lastValidatedAt": "2026-09-18T14:05:12.000Z",
"source": "app_store_server_api"
}
}