Revenue
Connect Creem
Creem sends checkouts, subscription payments and refunds to a webhook signed with its secret. Checkout metadata links each payment to a visit.
Set up the webhook
Copy the webhook URL
In MetricRaven, open Settings → Integrations → Creem and copy the webhook URL.
Add a webhook in Creem
In the Creem dashboard, open Settings → Webhooks → New webhook. Paste the URL and keep
checkout.completed,subscription.paidandrefund.createdselected. For subscription goals and live subscriptions and MRR, also select the othersubscription.*events (active, trialing, update, past_due, unpaid, paused, scheduled_cancel, canceled, expired). They are all selected by default; the credits events are ignored. Then choose Create webhook.Paste the signing secret in MetricRaven
Open the webhook, choose Reveal next to its signing secret (
whsec_…), paste it into the Creem panel and choose Connect Creem.Import existing subscriptions (optional)
Webhooks only report subscriptions that change after you connect. Once connected, choose Import existing subscriptions on the Creem panel and paste a live API key (
creem_…; acreem_test_…key on a Test mode connection) once so live subscriptions and MRR include the ones you already have. Create it under Settings → API keys with only the subscriptions read permission. The key is used for that import only and is not stored.
Pass the visitor ID at checkout
Creem returns checkout metadata in checkout.completed and keeps it on the subscription, so renewals carry it too. Use these keys:
| Key | Value |
|---|---|
| metricraven_visitor_id | The visitor ID from getVisitorId() (24 or 32 hex characters). |
| metricraven_user_id | Optional. Your signed-in user's ID, set on the server, matching the Identify API. |
| metricraven_plan | Optional. A plan name for reports; otherwise the product from the checkout is used. |
Read the visitor ID in the browser
The MetricRaven script exposes
window.analytics.getVisitorId(). Read it when checkout starts and send it to your checkout code:script.js// Read this in the visitor's browser when they start checkout. const visitorId = window.analytics?.getVisitorId() ?? null; // Send visitorId to your own checkout endpoint alongside its usual request data. // Use the authenticated user ID from your backend; do not trust a browser-supplied user ID.Add it to the checkout
Checkout API// Server: create a Creem checkout (POST /v1/checkouts) with your API key. const response = await fetch("https://api.creem.io/v1/checkouts", { method: "POST", headers: { "x-api-key": process.env.CREEM_API_KEY, "Content-Type": "application/json" }, body: JSON.stringify({ product_id: "prod_YOUR_PRODUCT_ID", success_url: "https://example.com/success", ...(user ? { customer: { email: user.email } } : {}), metadata: { ...(visitorId ? { metricraven_visitor_id: visitorId } : {}), ...(user ? { metricraven_user_id: user.id } : {}), }, }), }); const { checkout_url } = await response.json(); // Redirect the visitor to checkout_urlFor a payment link, add
metadata[metricraven_visitor_id]:Payment link// Browser: payment links turn ?metadata[<key>]= into checkout metadata. const url = new URL("https://creem.io/payment/prod_YOUR_PRODUCT_ID"); const visitorId = window.analytics?.getVisitorId(); if (visitorId) url.searchParams.set("metadata[metricraven_visitor_id]", visitorId); window.location.href = url.toString();
MetricRaven links each payment to a visit using the first of these that is available:
- The
metricraven_visitor_idpassed through checkout. - The
metricraven_user_id(or the provider's customer external ID), matched to a visitor you linked with the Identify API. - An earlier payment from the same provider customer, so renewals keep the original attribution.
- The checkout email, matched to an email from a server-side or signed Identify call (unsigned browser identify doesn't count).
- The checkout email, matched to a browser that called payment({ email }) within an hour of the payment.
Verify it works
After a delivery, the Creem panel in Settings → Integrations shows Connected, the number of verified events and the last event type. A live payment appears in Revenue, converted to your reporting currency; with a visitor ID it is credited to that visit's source in Traffic.
If the panel says a delivery was rejected, the signing secret doesn't match. Paste it again or generate a replacement.
Test mode
Creem test mode (API test-api.creem.io) has its own API keys and webhooks. Turn on Test mode, then turn on Test Mode in Creem and add the webhook there: everything this connection receives is recorded as test data, and a delivery whose payload says it comes from live mode is ignored. The subscription import reads test-api.creem.io and takes test mode keys (creem_test_…); a live key is refused, and a live connection refuses test keys. Never paste a test mode webhook secret into a live connection.
- Test payments and subscriptions are stored marked as test data and count in that site's revenue, MRR and subscriptions. The provider's panel shows a Test mode badge, and the Revenue tab a Test mode notice.
- Test payments don't count toward your plan's monthly events and send no payment alerts.
- The mode is chosen when you connect. Replacing a key or secret keeps it; to switch between test and live, disconnect and connect again. Test data already recorded stays.
- Connect test mode to a separate test website, so test payments never sit next to real revenue. See Test mode.
Details
- Revenue is the order's
amount_paid(including tax), converted from cents. A subscription's first charge arrives both with the checkout and assubscription.paid; it is the same transaction and counts once. Latersubscription.paidcharges are renewals. A proration charge (an upgrade mid-period) is revenue but not a renewal. Trials and 100% discounts are not revenue. - Each
refund.createdreduces its payment once, even when Creem resends it. A cancellation is not a refund. Adispute.createdreduces its payment when it opens, because Creem refunds the buyer then; Creem sends no dispute outcome, so a dispute you win isn't added back. - Signature: the
creem-signatureheader (HMAC-SHA256 of the body with your signing secret). Standard Webhooks headers (webhook-id,webhook-timestamp,webhook-signature) are accepted too, and such deliveries older than five minutes are rejected. - Test mode and live mode have separate webhooks and API keys. Connect a test mode webhook only with Test mode on.
- Live subscriptions and MRR: State from the subscription.* webhooks and the subscription on each checkout. MRR is the last full-period charge as paid, without tax (after discounts, and without VAT on tax-inclusive prices), per billing period; proration and trial charges don't change it. During a trial the plan's price (tax-exclusive) is kept for when it converts. A plan change makes MRR unavailable until the first charge at the new price. Scheduled cancellations stay live until the period ends; past due and unpaid subscriptions (Creem still retries) keep counting; paused ones add nothing. Import existing subscriptions once with an API key; those without a charge use the product's list price. Amounts in other currencies convert at the latest ECB rates. See the Revenue dashboard.
- Each delivery is verified with an HMAC signature over the exact request body, compared in constant time. Unsigned or altered requests are rejected with
401and never change revenue. - Redelivered events are recognized and ignored, so provider retries never add a payment twice. Refunds reduce the original payment and never exceed it.
- The signing secret is stored encrypted, bound to this site, and never shown in reports, share links or logs. Disconnecting deletes it; imported revenue stays in your reports.
- Free trials and zero-amount orders are not revenue. A subscription cancellation is not a refund: revenue already paid stays.
- Webhooks deliver new events only: payments from before you connected are not imported. Subscriptions from before you connected can be imported once from the provider's panel where its API allows it.
- Use one revenue path per purchase: don't also send the same orders through the Payments API.