Revenue

Connect Creem

On this page

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

  1. Copy the webhook URL

    In MetricRaven, open Settings → Integrations → Creem and copy the webhook URL.

  2. Add a webhook in Creem

    In the Creem dashboard, open Settings → Webhooks → New webhook. Paste the URL and keep checkout.completed, subscription.paid and refund.created selected. For subscription goals and live subscriptions and MRR, also select the other subscription.* 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.

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

  4. 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_…; a creem_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:

KeyValue
metricraven_visitor_idThe visitor ID from getVisitorId() (24 or 32 hex characters).
metricraven_user_idOptional. Your signed-in user's ID, set on the server, matching the Identify API.
metricraven_planOptional. A plan name for reports; otherwise the product from the checkout is used.
  1. 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.
  2. 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_url

    For 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:

  1. The metricraven_visitor_id passed through checkout.
  2. The metricraven_user_id (or the provider's customer external ID), matched to a visitor you linked with the Identify API.
  3. An earlier payment from the same provider customer, so renewals keep the original attribution.
  4. The checkout email, matched to an email from a server-side or signed Identify call (unsigned browser identify doesn't count).
  5. 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 as subscription.paid; it is the same transaction and counts once. Later subscription.paid charges are renewals. A proration charge (an upgrade mid-period) is revenue but not a renewal. Trials and 100% discounts are not revenue.
  • Each refund.created reduces its payment once, even when Creem resends it. A cancellation is not a refund. A dispute.created reduces 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-signature header (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 401 and 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.