Ramadan Last 10 Nights Campaign

Used by thousands of students worldwide - help us reach 150 members

... / 150 members...
APIIn-App Purchases

In-App Purchases

/iap

Mobile 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.

GET/iap/subscription

Get the current user's mobile subscription

Auth required

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).
Request
curl -X GET "https://app.ummahspot.com/iap/subscription" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "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"
  }
}
POST/iap/ios/validate

Validate an iOS App Store subscription and link it to the account

Auth required

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

transactionReceipt
string
Base64 App Store receipt. Required when no transaction id is sent, or when the server is not configured for the App Store Server API.
transactionId
string
StoreKit transaction id of the purchase.
originalTransactionId
string
StoreKit original transaction id identifying the subscription.
productId
string
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.
Request
curl -X POST "https://app.ummahspot.com/iap/ios/validate" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transactionReceipt":"string"}'
Response · 200
{
  "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"
  }
}