@lunora/payment — Creem

Creem is a Merchant-of-Record (MoR) for software. Like Polar and Dodo Payments, Creem is the legal seller of your product: it prices, collects, and remits sales tax / EU VAT across 190+ jurisdictions, issues the invoice under its own entity, and owns chargebacks and disputes. You never touch a tax table. This page covers wiring Creem into a Lunora app through @lunora/payment; for the provider itself, see Creem's official docs.

What Creem is, and when to choose it

Creem is product-based: you create real products (with prices) in the Creem dashboard and reference them by product id at checkout, which is exactly the shape @lunora/payment's priceId interface expects, so Creem slots in like Polar and Dodo rather than like a raw PSP. Checkout is a hosted, Creem-branded page; subscriptions are first-class objects (cancel, pause/resume, upgrade with proration); and there is a genuine hosted billing portal customers can open to manage their own payment methods and subscriptions.

Choose Creem when you want a MoR (no tax registration, no VAT filing) with a strong EU footprint and a clean product/subscription model, and you don't need programmatic refunds or usage-based billing.

Prerequisites

Store both as environment variables. Lunora's secrets registry declares the exact names @lunora/payment expects:

Install

Install the payment package alongside the official creem SDK. @lunora/payment never imports creem itself (you inject the client), so the SDK stays an ordinary dependency of your app, not a hard dependency of the package.

pnpm add @lunora/payment creem

Configure

The adapter takes the creem client by injection, typed as the structural CreemClientLike (its checkouts, customers, and subscriptions resources). A real Creem instance satisfies it without a cast — the shape exists only to keep @lunora/payment free of a hard creem dependency and the SDK's full types out of the published declarations; internally the adapter calls the real SDK methods.

import { Creem } from "creem";

const creem = new Creem({
    apiKey: env.CREEM_API_KEY,
    // server: "test", // → https://test-api.creem.io while developing
});

import { createCreemAdapter } from "@lunora/payment/creem";
import { Creem } from "creem";
import { createShardDO } from "./_generated/shard";

export const ShardDO = createShardDO({
    payment: (env) => {
        const client = new Creem({ apiKey: env.CREEM_API_KEY });

        return {
            adapter: createCreemAdapter({ client, webhookSecret: env.CREEM_WEBHOOK_SECRET }),
            // Grant plans from active/trialing subscriptions on these product ids.
            entitlements: {
                plans: { pro: { features: ["export"], priceIds: ["prod_pro"] } },
            },
            observability: (event) => console.log("[payment]", event.type, event),
        };
    },
});

ctx.payments is then wired by codegen onto ActionCtx wherever a lunora/ source imports @lunora/payment or reads ctx.payments.

Hosted checkout

Call the facade from an action. createCheckout reuses the reference's stored Creem customer (minting one only on first checkout), attaches an outbound idempotency key automatically, and returns a hosted url to redirect to. The priceId is a Creem product id.

import { action, v } from "./_generated/server";

export const subscribe = action.input({ productId: v.string() }).action(async ({ ctx, args: { productId } }): Promise<{ url: string }> => {
    const { url } = await ctx.payments.createCheckout({
        referenceId: ctx.auth.userId,
        priceId: productId, // Creem product id (prod_…)
        mode: "subscription", // or "payment" for a one-time purchase
        successUrl: "https://app.test/done",
        cancelUrl: "https://app.test/cancel",
        quantity: 1, // → the checkout's `units`
    });

    return { url };
});

Subscriptions

All subscription methods return the provider's reported truth, which the facade persists to the store.

Cancel: immediate vs. at period end

// Cancel immediately (default): access ends now.
await ctx.payments.cancelSubscription(subscriptionId);

// Cancel at period end: the customer keeps access until the current period ends.
await ctx.payments.cancelSubscription(subscriptionId, { atPeriodEnd: true });

The adapter maps this onto Creem's cancel mode: atPeriodEnd: true → { mode: "scheduled" }, otherwise { mode: "immediate" }. A scheduled cancel leaves Creem's subscription in scheduled_cancel, which the adapter still treats as active (it entitles until period end) while surfacing the pending cancellation via cancelAtPeriodEnd: true.

Upgrade / downgrade with proration

A plan change is expressed as a priceId patch and issued as a Creem upgrade to the new product, prorated and charged immediately:

// Adapter calls subscriptions.upgrade(id, { productId, updateBehavior: "proration-charge-immediately" })
const updated = await ctx.payments.adapter.updateSubscription(subscriptionId, { priceId: "prod_enterprise" });

proration-charge-immediately means the plan takes effect at once and the prorated difference is billed right away (Creem also supports proration-none). See Managing subscriptions.

Resume

await ctx.payments.adapter.resumeSubscription(subscriptionId); // → subscriptions.resume(id)

Billing portal

Give a customer a self-service portal to manage payment methods and subscriptions. The facade derives the customer from the store (never a caller-supplied id, so no IDOR) and calls Creem's generateBillingLinks:

export const portal = action.action(async ({ ctx }): Promise<{ url: string }> => {
    return ctx.payments.createPortalSession(ctx.auth.userId, "https://app.test/account");
});

The adapter reads the portal URL from Creem's customer_portal_link response field. See Customer Portal.

Webhooks

Creem signs every webhook with a single creem-signature header: hex(HMAC_SHA256(signingSecret, rawBody)), the HMAC-SHA256 of the raw request body, hex-encoded, with no timestamp in the scheme. The adapter verifies it with a constant-time comparison and fails closed on a missing secret or header.

import { webhookResponse } from "@lunora/payment";
import { httpAction, httpRouter } from "lunorash/server";
import { processWebhook } from "./billing";

export const app = httpRouter();

app.post(
    "/payment/webhook",
    httpAction(async (ctx, request) => {
        const body = await request.text();
        const signature = request.headers.get("creem-signature") ?? "";

        // `webhookResponse`, not `Response.json(...)`: only the JSON payload crosses the
        // `runAction` hop, so building the response by hand collapses the deliberate 500 on an
        // orphaned (out-of-order) event to a 200 and Creem never redelivers it.
        return webhookResponse(await ctx.runAction(processWebhook, { body, signature }));
    }),
);

import { internalAction, v } from "./_generated/server";

export const processWebhook = internalAction
    .input({ body: v.string(), signature: v.string() })
    .action(async ({ ctx, args: { body, signature } }): Promise<{ applied: boolean; status: number }> => {
        const request = new Request("https://internal/payment/webhook", {
            body,
            headers: { "creem-signature": signature },
            method: "POST",
        });
        const response = await ctx.payments.handleWebhook(request);
        const result = (await response.json()) as { applied?: boolean };

        return { applied: result.applied ?? false, status: response.status };
    });

Once verified, handleWebhook normalizes the event through Lunora's state machine and returns 200 once applied or deduplicated, so Creem stops retrying; a duplicate is safe by construction (the event id keys an append-only log). The one exception is an orphaned event — one whose subscription or customer row has not been created yet, i.e. an out-of-order delivery — which returns 500 so Creem redelivers it after the parent row lands.

Event mapping

Creem's top-level event carries id, eventType, and object. The adapter maps each eventType to a normalized transition:

Limitations

Creem is a Merchant-of-Record, so it owns money movement. Several PSP-style operations therefore throw a PROVIDER_ERROR rather than silently no-op:

• Refunds are dashboard-only. Creem exposes no SDK/API endpoint to initiate a refund, so refundPayment throws. Issue refunds from the Creem dashboard; the resulting refund.created webhook syncs the refunded amount back into the store.
• No usage metering. usageMetering is false. track still records to Lunora's own durable ledger (and check reads it), but nothing is forwarded to Creem.
• No manual capture / payment cancellation. capturePayment and cancelPayment throw, because Creem captures at checkout and owns the payment lifecycle.

Troubleshooting

Customers and getOrCreateCustomer

The facade only calls getOrCreateCustomer when the store holds no Creem customer for the referenceId, i.e. the first checkout (a caller-supplied customerId is ignored — the customer is always derived from the store for the authorized reference). The adapter tries customers.create first, then (on the duplicate-email error Creem returns for an existing email) falls back to customers.retrieve by email, an idempotent get-or-create.

Related

• @lunora/payment: the provider-agnostic API, ctx.payments, entitlements, and the store schema.
• @lunora/scheduler: drive the reconcile sweep that re-fetches provider truth for drifted rows.
• Studio: the Payments panel (under Operations) shows synced customers, subscriptions, and Creem webhook events.
• Creem docs · Webhooks · Managing subscriptions · Customer Portal