@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 is a complete, standalone guide to wiring Creem into a Lunora app through @lunora/payment — everything below is grounded in the actual createCreemAdapter surface and 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 — 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

npm install @lunora/payment creem

yarn add @lunora/payment creem

bun add @lunora/payment creem

Configure

The adapter takes a structural CreemClientLike shim by injection. This keeps @lunora/payment free of a hard creem dependency and — importantly — lets you map the real SDK's argument shapes onto the small, stable surface the adapter calls. The shim shape is:

interface CreemClientLike {
    checkouts: {
        create: (request) => Promise<Record<string, unknown>>;
        retrieve: (checkoutId: string) => Promise<Record<string, unknown>>;
    };
    customers: {
        create: (request) => Promise<Record<string, unknown>>;
        generateBillingLinks: (request) => Promise<Record<string, unknown>>;
        retrieve?: (request) => Promise<Record<string, unknown>>; // optional: recover a duplicate-email create
    };
    subscriptions: {
        cancel: (subscriptionId: string, request?) => Promise<Record<string, unknown>>;
        get: (subscriptionId: string) => Promise<Record<string, unknown>>;
        resume: (subscriptionId: string) => Promise<Record<string, unknown>>;
        upgrade: (subscriptionId: string, request) => Promise<Record<string, unknown>>;
    };
}

import { Creem } from "creem";

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

import type { CreemClientLike } from "@lunora/payment/creem";

const client: CreemClientLike = {
    checkouts: {
        create: (request) => creem.checkouts.create(request),
        retrieve: (checkoutId) => creem.checkouts.retrieve(checkoutId),
    },
    customers: {
        generateBillingLinks: (request) => creem.customers.generateBillingLinks(request),
        // Real SDK signature is positional: retrieve(customerId?, email?)
        retrieve: (request) => creem.customers.retrieve(undefined, request.email as string),
        // Not on the SDK's `customers` resource — call the REST endpoint directly.
        create: async (request) =>
            (await fetch("https://api.creem.io/v1/customers", {
                body: JSON.stringify({ email: request.email, name: request.name }),
                headers: { "content-type": "application/json", "x-api-key": env.CREEM_API_KEY },
                method: "POST",
            }).then((response) => response.json())) as Record<string, unknown>,
    },
    subscriptions: {
        cancel: (id, request) => creem.subscriptions.cancel(id, request ?? {}),
        get: (id) => creem.subscriptions.get(id),
        resume: (id) => creem.subscriptions.resume(id),
        upgrade: (id, request) => creem.subscriptions.upgrade(id, request),
    },
};

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

export const ShardDO = createShardDO({
    payment: (env) => {
        const creem = new Creem({ apiKey: env.CREEM_API_KEY });
        const client = buildCreemShim(creem, env); // the shim from the previous step

        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 — 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 { 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") ?? "";

        return Response.json(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 always returns 200 so Creem stops retrying — duplicate or out-of-order deliveries are safe by construction (the event id keys an append-only log).

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 — Creem captures at checkout and owns the payment lifecycle.

Troubleshooting

Customers and getOrCreateCustomer

The facade only calls getOrCreateCustomer when a reference has no stored Creem customer and no customerId was passed — i.e. the first checkout. 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. Because Creem also creates the customer implicitly at checkout (the checkout accepts customer.email), you can alternatively omit create from the shim and let checkout mint the customer.

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 Logs) shows synced customers, subscriptions, and Creem webhook events.
• Creem docs · Webhooks · Managing subscriptions · Customer Portal