SyntaxCircus.RevenueCat 0.1.8

There is a newer version of this package available.
See the version list below for details.
dotnet add package SyntaxCircus.RevenueCat --version 0.1.8
                    
NuGet\Install-Package SyntaxCircus.RevenueCat -Version 0.1.8
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SyntaxCircus.RevenueCat" Version="0.1.8" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="SyntaxCircus.RevenueCat" Version="0.1.8" />
                    
Directory.Packages.props
<PackageReference Include="SyntaxCircus.RevenueCat" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add SyntaxCircus.RevenueCat --version 0.1.8
                    
#r "nuget: SyntaxCircus.RevenueCat, 0.1.8"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package SyntaxCircus.RevenueCat@0.1.8
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=SyntaxCircus.RevenueCat&version=0.1.8
                    
Install as a Cake Addin
#tool nuget:?package=SyntaxCircus.RevenueCat&version=0.1.8
                    
Install as a Cake Tool

SyntaxCircus.RevenueCat

Build NuGet License: MIT

Backend-side RevenueCat integration: HMAC webhook signature verification, a strict-by-default webhook reader, and typed REST clients for subscriber verification, transaction reconciliation, product publishing, and anonymous-user aliasing. No third-party dependency — everything is plain HttpClient + System.Text.Json + System.Security.Cryptography against RevenueCat's REST API.

For client-side (MAUI) RevenueCat integration, see SyntaxCircus.RevenueCat.Maui.

No support guaranteed. Published as-is and maintained on a best-effort basis. Issues and PRs are welcome, but there's no SLA — fork it or vendor what you need if that's not enough.

Setup

builder.Services.AddRevenueCat(builder.Configuration); // binds "RevenueCat", registers all 5 typed clients
{
  "RevenueCat": {
    "ApiKey": "sk_...",
    "PublicApiKey": "...",
    "WebhookSecret": "...",
    "WebhookSignatureToleranceSeconds": 300,
    "WebhookMaxBodyBytes": 262144,
    "ProjectId": "...",
    "ProductSyncApiKey": "...",
    "ProductSyncAppIds": ["app_..."],
    "ExpectedTransactionEnvironment": "Production"
  }
}

Webhook endpoint

app.MapPost("/webhooks/revenuecat", async (HttpRequest request, IOptions<RevenueCatOptions> options, CancellationToken ct) =>
{
    var result = await RevenueCatWebhookReader.ReadAndVerifyAsync(request, options.Value, ct);

    return result.Status switch
    {
        RevenueCatWebhookStatus.Unauthorized => Results.Unauthorized(),
        RevenueCatWebhookStatus.Malformed => Results.BadRequest(),
        RevenueCatWebhookStatus.TooLarge => Results.StatusCode(StatusCodes.Status413PayloadTooLarge),
        _ => HandleVerifiedEvent(result.Payload!, result.RawBody!), // your idempotency store + processing
    };
});

By default, RevenueCatOptions.RequireWebhookSecret is true — if WebhookSecret isn't configured, the reader rejects every request outright rather than silently accepting unverified ones. Only set RequireWebhookSecret to false for local development. This is the package's whole reason for existing: a hand-rolled webhook auth check is an easy mistake to make and a real vulnerability — this reader closes that gap by construction.

ReadAndVerifyAsync enforces RevenueCatOptions.WebhookMaxBodyBytes before doing any parsing/verification work, buffers the raw request body as bytes (so it can be HMAC-verified and JSON-deserialized without double-consuming the stream), verifies the X-RevenueCat-Webhook-Signature header (t=<unix_timestamp>,v1=<hmac_sha256_hex>, HMAC-SHA256 over "{timestamp}.{rawBody}", constant-time compared, with WebhookSignatureToleranceSeconds — default 300s — as a replay-window tolerance against the timestamp, per RevenueCat's documented webhook signing scheme), and deserializes the envelope — checking for a present event.id (use it as your idempotency key; this package doesn't own storage or dispatch, that's yours).

REST clients

  • IRevenueCatPurchaseVerifier.VerifyAsync(new RevenueCatPurchaseVerificationRequest(appUserId, productId, transactionId)) — in default V1 mode, confirms a purchase against the subscriber's non_subscriptions, falling back to the transactions API if the subscriber record hasn't caught up yet.
  • IRevenueCatTransactionService.GetTransactionsForCandidatesAsync(candidateAppUserIds, startDate, endDate) — reconciles transactions for a caller-supplied set of candidate app_user_ids by querying GET v1/subscribers/{app_user_id} per id and aggregating non_subscriptions. This is the production-realistic reconciliation path: RevenueCat's REST API has no bulk "list transactions in a date range" endpoint. GetTransactionsAsync(startDate, endDate) still exists for consumers fronting RevenueCat with their own aggregation proxy at RevenueCatOptions.TransactionsEndpoint, but that endpoint doesn't exist on RevenueCat's own API.
  • IRevenueCatProductCatalogService.PublishOneTimeProductAsync(...) — creates or updates a one-time product across one or more RevenueCat apps (v2 API).
  • IRevenueCatSubscriberAliasClient.CreateAliasAsync(canonicalAppUserId, anonymousAppUserId) — aliases an anonymous purchaser to an identified user after login.
  • IRevenueCatSubscriberDeletionClient.DeleteSubscriberAsync(appUserId) — permanently deletes a RevenueCat subscriber (e.g. when a user closes their account). In default V1 mode, calls DELETE v1/subscribers/{app_user_id} and requires RevenueCat:ApiKey (a v1 secret key) — PublicApiKey cannot delete subscribers, and ResolveSecretApiKeyOrThrow throws InvalidOperationException if only that's configured. Returns RevenueCatSubscriberDeletionResult.NotFound (not an exception) for an already-gone subscriber; any other non-success response throws HttpRequestException with StatusCode set so callers can retry on 429/5xx.

Opt-in V2 customer operations

Existing consumers keep V1 behavior by default. To use V2 for purchase verification, transaction reconciliation and customer deletion, configure:

{
  "RevenueCat": {
    "CustomerApiVersion": "V2",
    "ApiKey": "<v2-secret-key>",
    "ProjectId": "proj_...",
    "CustomerAppIds": ["app_..."],
    "CustomerApiBaseUrl": "https://api.revenuecat.com/v2/",
    "ExpectedTransactionEnvironment": "Production"
  }
}

CustomerApiVersion defaults to V1. Selection is explicit: key prefixes do not reliably distinguish V1 from V2 keys, and authentication failures never trigger an automatic switch between API versions. V2 requires a server secret ApiKey and ProjectId; PublicApiKey is not a substitute. Leave the base URL at its default for RevenueCat itself.

V2 permissions:

Operation Required permissions
Read purchases for known customers / verify a one-time purchase customer_information:purchases:read, project_configuration:products:read
Scan project customers for reconciliation The above plus customer_information:customers:read
Delete a customer customer_information:customers:read_write

CustomerAppIds restricts V2 purchases to the configured RevenueCat apps. Set it when a project contains multiple apps, especially if store product identifiers overlap. An empty list allows the whole project.

The existing interfaces select their implementation from this configuration:

  • GetTransactionsForCandidatesAsync reads every purchase page for the supplied customer IDs and filters by the requested time window.
  • GetTransactionsAsync scans customers and their purchases through the real V2 API. It can be substantially more expensive than candidate reconciliation; prefer candidates when the application already knows the relevant customers. In V1 it retains the existing custom aggregation-proxy behavior.
  • VerifyAsync verifies one-time purchases against the customer purchase list, resolves RevenueCat product IDs to store product identifiers, and retains the transaction environment guard. An owned purchase can verify; a refunded purchase cannot. Subscription verification is outside this client’s scope.
  • DeleteSubscriberAsync calls V2 customer deletion when selected. A missing customer remains an idempotent NotFound; authentication, rate-limit and server failures remain failures.

V2 purchase prices are gross USD from revenue_in_usd.gross, paired with currency USD. Store transaction identifiers are kept distinct from RevenueCat purchase IDs. Reconciliation includes purchase status; it is not a complete financial refund ledger.

V2 follows paginated responses with cycle/page limits and rejects pagination outside the expected origin and collection before sending credentials. Failed or malformed pages do not become successful empty or partial reconciliation results. The DI-registered V2 clients disable HTTP redirects; consumers constructing clients with their own HttpClient must also disable automatic redirects on its handler.

Aliasing remains a V1 operation. If using it alongside a V2 secret key, configure an appropriate V1-compatible PublicApiKey separately. Product publishing already uses V2 through its independent ProductSyncApiKey settings and is unaffected. Webhook handling is also unchanged.

Contracts checked against RevenueCat’s official customer API, customer resources, purchase API, and product API.

Transaction-environment guard

If your app has more than one deployed environment (e.g. UAT and Production) sharing one RevenueCat project, set ExpectedTransactionEnvironment (Sandbox or Production) on the deployment whose expectation you want enforced — left unset (the default), nothing here changes behavior:

var verified = await verifier.VerifyAsync(new RevenueCatPurchaseVerificationRequest(appUserId, productId, transactionId));
if (verified.Status == "environment_mismatch")
{
    // verified.Purchase is null - the transaction's real store environment (RevenueCatVerifiedPurchase.IsSandbox,
    // parsed from the subscriber endpoint's non_subscriptions.*.is_sandbox) didn't match ExpectedTransactionEnvironment.
}

This is independent of what any client believes its selected backend to be — a mobile client choosing "UAT" or "Production" locally is not proof of the underlying store transaction's real environment, so a UAT deployment could otherwise record a genuine production purchase (or vice versa) if a client's local selection doesn't match reality. RevenueCatTransactionEnvironmentMatcher.MatchesWebhookEnvironment(expected, revenueCatEvent.Environment) applies the identical check to the webhook path, since RevenueCatEvent.Environment already carries RevenueCat's own SANDBOX/PRODUCTION value — call it yourself before acting on a webhook event, the same way IRevenueCatPurchaseVerifier already does internally for verification. Both checks pass through unknown/unverifiable values (a null IsSandbox or a missing webhook Environment) rather than rejecting them, since an inability to verify isn't evidence of a mismatch.

RevenueCatApiKeyResolver returns configured V1 credential candidates in preference order (PublicApiKey, then ApiKey); it does not infer API compatibility from key prefixes. The subscriber/purchase/alias clients use these candidates for V1 calls. ResolveSecretApiKeyOrThrow is the exception — it's used only by IRevenueCatSubscriberDeletionClient, which RevenueCat restricts to ApiKey specifically and never accepts PublicApiKey for.

Contributing

Issues and pull requests are welcome:

  • Keep changes focused, with a clear description of the behavior change.
  • Match the existing code style (see .editorconfig).
  • Call out any breaking changes to the public API in your PR description.

License

MIT — see LICENSE.txt.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.10 143 10/24/2026
0.1.9 103 10/24/2026
0.1.8 119 10/16/2026
0.1.7 133 9/22/2026
0.1.6 144 9/13/2026
0.1.5 177 9/6/2026
0.1.4 148 9/6/2026
0.1.3 151 8/30/2026
0.1.2 140 8/17/2026
0.1.1 144 8/16/2026