Documentation
Gumroad revenue attribution
Gumroad's current Ping documentation offers optional signing, off by default. This adapter requires signing. In Gumroad Settings → Advanced, set Ping URL to the site's /api/webhooks/gumroad/SITE_ID URL, enable Ping signing, and save the Ping signing secret in AnalyticFast Settings → Revenue. API access tokens are not signing secrets. Use separate seller credentials for separate analytics sites; a seller-wide signing secret shared between sites cannot cryptographically isolate the seller's own products. Use distinct product filters when distributing a seller's sales between sites.
X-Gumroad-Signature: t=SECONDS,v1=HEX authenticates the exact raw form body as HMAC-SHA256 of t + '.' + body. Timestamps must be within five minutes; retries have fresh signatures. Constant-time Web Crypto verification rejects missing, stale, malformed or incorrect signatures. The same sale ID is recorded once per site/provider even when delivered again with a new signature.
Unsigned Ping is rejected. API resource-subscription callbacks are not signed with the Ping secret and cannot use this endpoint. If your account does not offer signed Ping, use your trusted backend to fetch /v2/sales/:id with the seller's view_sales token and forward confirmed records through the authenticated server payments API. Never forward unverified Ping amounts/visitor IDs. An unguessable URL alone is weaker than signature or seller API verification because URLs leak in logs. The frozen provider interface needs no change for signed delivery and this adapter makes no outbound API calls.
The React-rendered docs can be inspected in Gumroad's official Ping documentation source, Ping payload implementation, API resource subscription docs and sale API docs. Reviewed 2026-11-12; signing was also confirmed in the deployed gumroad.com Ping page's JavaScript bundle.
Gumroad's payload builder also flattens custom fields into the top level. Do not name a buyer custom field price, sale_id, url_params, or another reserved financial/attribution field. The adapter rejects such payloads even if signed, because a signature would otherwise authenticate a buyer-overwritten value. Rename those custom fields and reconcile affected sales through the Sales API.
Carry visitor IDs in product links
Product URL query parameters come back in Ping's url_params. Add the two IDs before navigating, preserving existing application parameters. Example after the deferred tracker has loaded:
const ids = window.analyticfast?.attribution?.();
const link = document.querySelector('a[data-gumroad-product]');
if (link && ids?.ml_visitor_id) {
const url = new URL(link.href);
if (!url.searchParams.has('ml_visitor_id')) url.searchParams.set('ml_visitor_id', ids.ml_visitor_id);
if (ids.ml_session_id && !url.searchParams.has('ml_session_id')) url.searchParams.set('ml_session_id', ids.ml_session_id);
link.href = url.href;
}
This is manual link setup, not built-in tracker auto-tagging. Use a normal Gumroad product URL such as https://seller.gumroad.com/l/product; test overlays/embeds separately. In form delivery, the dictionary is encoded as url_params[ml_visitor_id] and url_params[ml_session_id]. JSON dictionaries are also accepted for previews. IDs are optional attribution hints; do not put personal information in them. URL parameter guide.
Money, renewals and refund limitations
resource_name=sale (or absent on older sale Pings) records sale_id, sale_timestamp, price, optional purchaser_id and subscription_id. is_recurring_charge=true marks a renewal with a new sale ID. Test Pings/self purchases, free purchases, preorder authorizations, gift-receiver copies and unrelated lifecycle events do not add revenue. Webhook email is parsed but is discarded by shared storage, not treated as identify consent.
All Ping amounts are USD cents, even when currency says EUR, JPY or another listed-product currency. A JPY-listed product with price=1500 means USD 15.00 here, not JPY 1500. We record USD and do not invent a foreign-exchange conversion. Buyer-presentment reporting requires the Sales API and is outside this Ping adapter.
resource_name=refund with refunded=true reverses the entire original sale once. Early refunds wait for the original sale. Ping provides no refund amount, refund ID or refund timestamp, so this adapter cannot safely account for partial refunds: it rejects those for backend reconciliation and never subtracts the original price as if it were the partial amount. Refund dates use the original sale timestamp, including late sale Pings whose refunded flag is already set; replaying those sales still records their gross original payment, deduplicated normally. Install trusted backend reconciliation before enabling revenue reporting for a store that issues partial refunds. Periodic reconciliation is also needed for missed Pings; Gumroad has a short response deadline and finite retries.
Product filters can use short_product_id (the URL slug), since opaque Gumroad product IDs can contain = which the shared filter validator excludes. Filtering includes the whole sale. The in-app Send test event is a no-write local preview; Gumroad's own Send test ping is deliberately ignored as test data. Use a dedicated analytics site and a real signed sale/refund to validate end to end.