# Connect Creem

> Receive Creem payments, renewals and refunds through a signed webhook and attribute them to visits.

Source: https://metricraven.com/docs/creem  
Markdown: https://metricraven.com/docs/creem.md  
Section: Revenue

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](https://metricraven.com/docs/goals-funnels#payment-provider-goals) and [live subscriptions and MRR](https://metricraven.com/docs/revenue-dashboard#mrr-by-provider), 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](https://metricraven.com/docs/creem#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. |

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:

   ```javascript
   // 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**

   ```javascript title="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]`:

   ```javascript title="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](https://metricraven.com/docs/identify-users).
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](https://metricraven.com/docs/identify-users) call (unsigned browser identify doesn't count).
5. The checkout email, matched to a browser that called [payment({ email })](https://metricraven.com/docs/attribute-by-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](https://metricraven.com/docs/connect-payment-provider#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](https://metricraven.com/docs/creem#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](https://metricraven.com/docs/revenue-dashboard#mrr-by-provider).
- 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.
