Subscription Receipt Token
Subscription Receipt Tokens (SRTs) are a key aspect of SDK operations, primarily used for internal purposes. These tokens contain "entitlements," which specify the features a user can currently access. SRTs effectively unlock features within the app and serve as the main authentication method when interacting with external backend resources.
Similar to other token types, SRTs are JSON Web Tokens (JWTs), making them digitally signed and time-limited. By default, an SRT has a lifespan of 7 days. During this time, the SDK typically does not attempt to refresh the token. Consequently, if a customer's subscription expires, the SRT remains valid for up to 7 days, effectively offering a grace period. Apps can override this by "force-refreshing" the tokens if needed.
Force Refreshing Tokens
The default lifespan of 7 days ensures effective caching, reducing the need for frequent API requests. However, there are times when apps must verify that the SRT reflects the latest entitlements. For instance, when a customer upgrades their subscription, the app must confirm that the newly purchased entitlements are updated in the SRT. Incorrectly implementing this refresh logic can significantly increase API requests, so it must be done carefully, following the guidelines below.
Respect the cooldown
Never force-refresh more often than once every 2 minutes.
Violating this rule can lead to backend rate limiting.
Right after a purchase
A force-refresh is recommended immediately after a successful purchase or upgrade, so the user’s new entitlements become available without delay.
When a purchase cannot be reliably detected
If your app cannot always detect when a purchase occurred, consider one of these safe strategies:
User-triggered refresh button
Add a button labeled “Refresh Subscription” or similar.
Enforce a minimum 2-minute cooldown before the button can be used again.
On app foregrounding
Perform a force-refresh when the app launches or returns to the foreground.
Respect the 2-minute cooldown here as well.
This aligns with common user behavior: many customers re-open an app right after making a purchase to confirm their entitlements have updated.
Search options and search result
This token type only supports the subscription id parameter for both the search options and search results. It's the only token type which supports the "force_refresh" parameter.
How to use this token
Usually, this token is only required internally by the SDK and will be forward as an Authorization Header value. However the SDK provides you additional methods to parse and extract the entitlements of that token via the Subscription & Entitlements module
Last updated